The Multithreaded Portable Runtime (MPR) is a portable runtime library for embedded applications.

Description:

The MPR provides management for logging, error handling, events, files, http, memory, ssl, sockets, strings, xml parsing, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. The MPR is a library and a C API that can be used in both C and C++ programs.

The MPR uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.

The MPR includes a memory allocator and generational garbage collector. The allocator is a fast, immediate coalescing allocator that will return memory back to the O/S if not required. It is optimized for frequent allocations of small blocks (< 4K) and uses a scheme of free queues for fast allocation.

The MPR provides a high-performance thread-pool to share threads as required to service clients. When a client request arrives, the MPR allocates an event queue called a dispatcher. This dispatcher then serializes all activity for the request so that it essentially runs single-threaded This simplifies the code as most interactions do not need to be lock protected. When a request has activity, it borrows a thread from the thread pool, does its work and then returns the thread to the thread pool. This all happens very quickly, so a small pool of threads are effectivelyshared over many requests. Thread are free to block if required, but typically non-blocking patterns are more economical. If you have non-MPR threads that need to call into the MPR, you must synchronize such calls via mprCreateEventOutside.

Components

Functions

Typedefs

Defines

Mpr

Primary MPR application control structure.

Description:: The Mpr structure stores critical application state information.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

API Stability:: Internal.

Fields:

char *	appDir	Path of directory containing app executable.
char *	appPath	Path name of application executable.
void *	appwebService	Appweb service object.
char **	argBuf	Space for allocated argv.
int	argc	Count of command line args.
cchar **	argv	Application command line args (not alloced).
bool	cmdlineLogging	App has specified log on the command line.
struct MprCmdService *	cmdService	Command service object.
MprCond *	cond	Sync after starting events thread.
bool	debugMode	Run in debug mode (no timers).
struct MprDispatcher *	dispatcher	Primary dispatcher.
char *	domainName	Domain portion.
void *	ediService	EDI object.
void *	ejsService	Ejscript service.
char *	emptyString	"" string.
void *	espService	ESP service object.
int	eventing	Servicing events thread is active.
struct MprEventService *	eventService	Event service object.
int	exitStrategy	How to exit the app.
MprTicks	exitTimeout	Request timeout when exiting.
struct MprFileSystem *	fileSystem	File system service object.
int	flags	Misc flags.
int	hasError	Mpr has an initialization error.
MprHeap *	heap	Memory heap control.
char *	hostName	Host name (fully qualified name).
void *	httpService	Http service object.
MprIdleCallback	idleCallback	Invoked to determine if the process is idle.
char *	ip	Public IP Address.
int	logBackup	Number of log files preserved when backing up.
MprFile *	logFile	Log file.
MprLogHandler	logHandler	Current log handler callback.
int	logLevel	Log trace level.
cchar *	logPath	Log path name.
ssize	logSize	Maximum log size.
MprOsThread	mainOsThread	Main OS thread ID.
MprHash *	mimeTypes	Table of mime types.
struct MprModuleService *	moduleService	Module service object.
MprMutex *	mutex	Thread synchronization used for global lock.
char *	name	Product name.
struct MprDispatcher *	nonBlock	Nonblocking dispatcher.
char *	oneString	"1" string.
struct MprOsService *	osService	O/S service object.
char *	pathEnv	Cached PATH env var. Used by MprCmd.
char *	serverName	Server name portion (no domain).
MprTicks	shutdownStarted	When the shutdown started.
struct MprSignalService *	signalService	Signal service object.
struct MprSocketService *	socketService	Socket service object.
MprSpin *	spin	Quick thread synchronization.
MprTime	start	When the MPR started.
MprFile *	stdError	Standard error file.
MprFile *	stdInput	Standard input file.
MprFile *	stdOutput	Standard output file.
MprList *	terminators	Termination callbacks.
void *	testService	Test service object.
struct MprThreadService *	threadService	Thread service object.
MprHash *	timeTokens	Date/Time parsing tokens.
char *	title	Product title.
int	verifySsl	Default verification of SSL certificates.
char *	version	Product version.
struct MprWaitService *	waitService	IO Waiting service object.
struct MprWorkerService *	workerService	Worker service object.

void assert (bool cond)

Assert that a condition is true.

Parameters:

cond	Boolean result of a conditional test.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprAddTerminator (MprTerminator terminator)

Add a service terminator.

Description:: Services may create shutdown notifiers called terminators that are informed when the application commences a shutdown. The terminator may be invoked several times and the service should take appropriate action based on the MPR state.

If the state parameter is set to MPR_STOPPING, the service should not accept any new requests, but otherwise not take any destructive actions. Note this state is required to be reversible if the shutdown is cancelled.

If the state is MPR_STOPPED, the service should cancel all running requests, close files and connections and release all resources. This state is not reversible.

This exitStrategy parameter is a flags word that defines the shutdown exit strategy. See mprShutdown for details.

Services may also call mprShouldDenyNewRequests to test if the MPR state is MPR_STOPPING and mprShouldAbortRequests if the state is MPR_STOPPED.

Parameters:

terminator

MprTerminator callback function.

API Stability:: Stable.

See Also:: mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprBreakpoint ()

Trigger a breakpoint.

Description:: This routine is invoked for assertion errors from mprAssert and errors from mprError. It is useful in debuggers as breakpoint location for detecting errors.

API Stability:: Stable.

See Also:: mprAddTerminator, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprCancelShutdown ()

Cancel a shutdown request.

Description:: A graceful shutdown request initiated via mprShutdown may be cancelled if the shutdown is still in progress and has not passed the point of no return. If the MPR is still in the MPR_STOPPING state, the shutdown may be cancelled. See mprGetState

Returns:: True if the shutdown can be cancelled. Returns false if a shutdown has not been requested or if the shutdown has advanced past the point of no return.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprCheckPassword (cchar *plainTextPassword, cchar *passwordHash)

Check a plain-text password against the defined hashed password.

Parameters:

plainTextPassword	User's plain-text-password to check.
passwordHash	Required password in hashed format previously computed by mprMakePassword.

Returns:: True if the password is correct.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

Mpr * mprCreate (int argc, char **argv, int flags)

Initialize the application by creating an instance of the MPR.

Description:: Initializes the MPR and creates an Mpr control object. The Mpr Object manages all MPR facilities and services. This must be called before using any MPR API. When processing is complete, you should call mprDestroy before exiting the application.

Parameters:

argc	Count of command line args.
argv	Command line arguments for the application. Arguments may be passed into the Mpr for retrieval by the unit test framework.
flags	Set MPR_USER_EVENTS_THREAD if you will manage calling mprServiceEvents manually if required. There are three styles of MPR applications with respect to servicing events: 1) Applications that don't require servicing events for I/O, commands or timers 2) Applications that call mprServiceEvents directly from their main program 3) Applications that have a dedicated service events thread Applications that do not perform I/O, run commands or create events may not need a service events thread. While creating one will do no harm, performance may be enhanced for these applications by specifying MPR_USER_EVENTS_THREAD. Applications that have not forground processing requirements may invoke mprServiceEvents from their main program instead of creating a service events thread. This saves one thread. The default is to create a service events thread so the full scope of MPR services are supported.

Returns:: Returns a pointer to the Mpr object.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprCreateOsService ()

Create and initialze the O/S dependent subsystem.

Description:: Called internally by the MPR. Should not be called by users.

API Stability:: Internal.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprCryptPassword (cchar *password, cchar *salt, int rounds)

Encrypt a password using the Blowfish algorithm.

Parameters:

password	User's password to encrypt.
salt	Salt text to add to password. Helps to make each user's password unique.
rounds	Number of times to encrypt. More times, makes the routine slower and passwords harder to crack.

Returns:: The encrypted password.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprDaemon ()

Convert the process into a daemon on unix systems.

Description:: This converts the current process into a detached child without a parent.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprDecode64 (cchar *str)

Decode a null terminated string using base-46 encoding.

Description:: Decoding will terminate at the first null or '='.

Parameters:

str	String to decode.

Returns:: Buffer containing the encoded data.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprDecode64Block (cchar *buf, ssize *len, int flags)

Decode a null terminated string using base-46 encoding.

Parameters:

buf	String to decode.
len	Return parameter with the Length of the decoded data.
flags	Set to MPR_DECODE_TOKEQ to stop at the first '='.

Returns:: Buffer containing the encoded data and returns length in len.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprDestroy ()

Destroy the MPR and all services using the MPR.

Description:: This call terminates the MPR and all services.

An application initializes the MPR by calling mprCreate. This creates the Mpr object, the memory allocator, garbage collector and other services. An application exits by invoking mprDestroy or by calling mprShutdown then mprDestroy.

There are two styles of MPR applications with respect to shutdown:

1) Applications that have a dedicated service events thread.

2) Applications that call mprServiceEvents directly from their main program.

Applications that have a service events thread can call mprDestroy directly from their main program when ready to exit. Applications that call mprServiceEvents from their main program will typically have some other MPR thread call mprShutdown to initiate a shutdown sequence. This will stop accepting new requests or connections and when the application is idle, the mprServiceEvents routine will return and then the main program can call then call mprDestroy.

Once the shutdown conditions are satisfied, a thread executing mprServiceEvents will return from that API and then the application should call mprDestroy and exit().

If an application needs to tailor how it exits with respect to current requests, use mprShutdown first to specify a shutdown strategy.

Returns:: True if the MPR can be destroyed. Returns false if the exit strategy MPR_EXIT_SAFE has been defined via mprShutdown and current requests have not completed within the exit timeout period defined by mprSetExitTimeout. In this case, the shutdown is cancelled and normal operations continue.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprEmptyString ()

Reference to a permanent preallocated empty string.

Returns:: An empty string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprEncode64 (cchar *str)

Encode a string using base-46 encoding.

Parameters:

str	String to encode.

Returns:: Buffer containing the encoded string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprEncode64Block (cchar *buf, ssize len)

Encode buffer using base-46 encoding.

Parameters:

buf	Buffer to encode.
len	Length of the buffer to encode.

Returns:: Buffer containing the encoded string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprEscapeCmd (cchar *cmd, int escChar)

Encode a string escaping typical command (shell) characters.

Description:: Encode a string escaping all dangerous characters that have meaning for the unix or MS-DOS command shells.

Parameters:

cmd	Command string to encode.
escChar	Escape character to use when encoding the command.

Returns:: An allocated string containing the escaped command.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprEscapeHtml (cchar *html)

Encode a string by escaping typical HTML characters.

Description:: Encode a string escaping all dangerous characters that have meaning in HTML documents.

Parameters:

html	HTML content to encode.

Returns:: An allocated string containing the escaped HTML.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprEscapeSQL (cchar *cmd)

Encode a string by escaping SQL special characters.

Description:: Encode a string escaping all dangerous characters that have meaning in SQL commands.

Parameters:

cmd	SQL command to encode.

Returns:: An allocated string containing the escaped SQL command.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetAppDir ()

Get the application directory.

Description:: Get the directory containing the application executable.

Returns:: A string containing the application directory.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetAppName ()

Get the application name defined via mprSetAppName.

Returns:: The one-word lower case application name defined via mprSetAppName.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetAppPath ()

Get the application executable path.

Returns:: A string containing the application executable path.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetAppTitle ()

Get the application title string.

Returns:: A string containing the application title string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetAppVersion ()

Get the application version string.

Returns:: A string containing the application version string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprGetCmdlineLogging ()

Get if command line logging is being used.

Description:: Logging may be initiated by invoking an MPR based program with a "–log" switch. This API assists programs to tell the MPR that command line logging has been used.

Returns:: True if command line logging is in use.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprGetDebugMode ()

Get the debug mode.

Description:: Returns whether the debug mode is enabled. Some modules observe debug mode and disable timeouts and timers so that single-step debugging can be used.

Returns:: Returns true if debug mode is enabled, otherwise returns false.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetDomainName ()

Get the application domain name string.

Returns:: A string containing the application domain name string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetEndian ()

Return the endian byte ordering for the application.

Returns:: MPR_LITTLE_ENDIAN or MPR_BIG_ENDIAN.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetError ()

Return the error code for the most recent system or library operation.

Description:: Returns an error code from the most recent system call. This will be mapped to be either a POSIX error code or an MPR error code.

Returns:: The mapped error code.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetExitStatus ()

Get the exit status.

Description:: Get the exit status set via mprShutdown May be called after mprDestroy

Returns:: The proposed application exit status.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetHostName ()

Get the application host name string.

Returns:: A string containing the application host name string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetIpAddr ()

Get the application IP address string.

Returns:: A string containing the application IP address string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetLogLevel ()

Get the current logging level.

Returns:: The current log level.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetMD5 (cchar *str)

Get an MD5 checksum.

Parameters:

str	String to examine.

Returns:: An allocated MD5 checksum string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetMD5WithPrefix (cchar *buf, ssize len, cchar *prefix)

Get an MD5 checksum with optional prefix string and buffer length.

Parameters:

buf	Buffer to checksum.
len	Size of the buffer.
prefix	String prefix to insert at the start of the result.

Returns:: An allocated MD5 checksum string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

Mpr * mprGetMpr ()

Return the MPR control instance.

Description:: Return the MPR singleton control object.

Returns:: The MPR control object.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetOsError ()

Return the O/S error code.

Description:: Returns an O/S error code from the most recent system call. This returns errno on Unix systems or GetLastError() on Windows.

Returns:: The O/S error code.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetPassword (cchar *prompt)

Get a password from the terminal console.

Parameters:

prompt

Text prompt to display before reading the password.

Returns:: The entered password.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetRandomBytes (char *buf, ssize size, bool block)

Get some random data.

Parameters:

buf	Reference to a buffer to hold the random data.
size	Size of the buffer.
block	Set to true if it is acceptable to block while accumulating entropy sufficient to provide good random data. Setting to false will cause this API to not block and may return random data of a lower quality.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetRandomString (ssize size)

Get some random data in ascii.

Parameters:

size	Size of the random data string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

cchar * mprGetServerName ()

Get the application server name string.

Returns:: A string containing the application server name string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetSHA (cchar *str)

Get an SHA1 checksum.

Parameters:

str	String to examine.

Returns:: An allocated SHA1 checksum string.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetSHABase64 (cchar *str)

Get an SHA1 checksum of a null terminated string.

Parameters:

str	String to checksum.

Returns:: An allocated string containing an SHA1 checksum.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprGetSHAWithPrefix (cchar *buf, ssize len, cchar *prefix)

Get an SHA1 checksum with optional prefix string and buffer length.

Parameters:

buf	Buffer to checksum.
len	Size of the buffer.
prefix	String prefix to insert at the start of the result.

Returns:: An allocated string containing an SHA1 checksum.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprGetState ()

Get the MPR execution state.

Returns:: MPR_CREATED, MPR_STARTED, MPR_STOPPING, MPR_STOPPED, MPR_DESTROYING, or MPR_DESTROYED.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprIsDestroyed ()

Determine if the MPR has finished.

Description:: This is true if the MPR services have been shutdown completely. This is typically used to determine if the App has been shutdown.

Returns:: True if the App has been instructed to exit and all the MPR services have been destroyed.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprIsDestroying ()

Test if the application is terminating and core services are being destroyed All request should immediately terminate.

Returns:: True if the application is in the process of exiting and core services should also exit.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprIsIdle (bool traceRequests)

Determine if the App is idle.

Description:: This call returns true if the App is not currently servicing any requests. By default this returns true if the MPR dispatcher, worker thread and command subsytems are idle. Callers can replace or augment the standard idle testing by definining a new idle callback via mprSetIdleCallback.

Note: this routine tests for worker threads but ignores other threads created via mprCreateThread

Parameters:

traceRequests

If true, emit trace regarding running requests.

Returns:: True if the App are idle.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprIsStopped ()

Test if the application is stopped If this routine returns true, the application shutdown has passed the point of no return.

No new requests should be accepted and current requests should be aborted. Use #mprIsStopping to test if shutdown has been initiated but current requests may continue. Use #mprIsDestroyed to test if the application has completed its shutdown

Returns:: True if the application is in the process of exiting.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprIsStopping ()

Test if the application is stopping If mprIsStopping is true, the application has commenced a shutdown.

No new requests should be accepted and current request should complete if possible. Use mprIsDestroyed to test if the application has completed its shutdown

Returns:: True if the application is in the process of exiting.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprMakeArgv (cchar *command, cchar ***argv, int flags)

Make a argv style array of command arguments.

Description:: The given command is parsed and broken into separate arguments and returned in a null-terminated, argv array. Arguments in the command may be quoted with single or double quotes to group words into one argument. Use back-quote "\\" to escape quotes. This routine allocates memory and must not be called before mprCreate. Consider mprParseArgs if you need to convert a command line before calling mprCreate

Parameters:

command	Command string to parse.
argv	Output parameter containing the parsed arguments.
flags	Set to MPR_ARGV_ARGS_ONLY if the command string does not contain a program name. In this case, argv[0] will be set to "".

Returns:: The count of arguments in argv.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprMakePassword (cchar *password, int saltLength, int rounds)

Make a password hash for a plain-text password using the Blowfish algorithm.

Parameters:

password	User's password to encrypt.
saltLength	Length of salt text to add to password. Helps to make each user's password unique.
rounds	Number of times to encrypt. More times, makes the routine slower and passwords harder to crack.

Returns:: The encrypted password.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprMakeSalt (ssize size)

Make salt for adding to a password.

Parameters:

size	Size in bytes of the salt text.

Returns:: The random salt text.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprNap (MprTicks msec)

Nap for a while.

Description:: This routine blocks and does not yield for GC. Only use it for very short naps.

Parameters:

msec	Number of milliseconds to sleep.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprParseArgs (char *command, char **argv, int maxArgs)

Make a argv style array of command arguments.

Description:: The given command is parsed and broken into separate arguments and returned in a null-terminated, argv array. Arguments in the command may be quoted with single or double quotes to group words into one argument. Use back-quote "\\" to escape quotes. This routine modifies supplied command parameter and does not allocate any memory and may be used before mprCreate is invoked.

Parameters:

command	Command string to parse.
argv	Array for the arguments.
maxArgs	Size of the argv array.

Returns:: The count of arguments in argv.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprRandom ()

Return a random number.

Returns:: A random integer.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprRestart ()

Restart the application.

Description:: This call immediately restarts the application. The standard input, output and error I/O channels are preserved. All other open file descriptors are closed.

If the application is started via a monitoring launch daemon such as launchd or appman, the application should not use this API, but rather defer to the launch daemon to restart the application. In that case, the application should simply do a shutdown via mprShutdown and/or mprDestroy

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprServicesAreIdle (bool traceRequests)

Determine if the MPR services.

Description:: This is the default routine invoked by mprIsIdle()

Parameters:

traceRequests

If true, emit trace regarding running requests.

Returns:: True if the MPR services are idle.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprSetAppName (cchar *name, cchar *title, cchar *version)

Set the application name, title and version.

Parameters:

name	One word, lower case name for the app.
title	Pascal case multi-word descriptive name.
version	Version of the app. Major-Minor-Patch. E.g. 1.2.3.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetAppPath (cchar *path)

Set the application executable path.

Parameters:

path	A string containing the application executable path.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprSetCmdlineLogging (bool on)

Set if command line logging was requested.

Description:: Logging may be initiated by invoking an MPR based program with a "–log" switch. This API assists programs to tell the MPR that command line logging has been used.

Parameters:

on	Set to true to indicate command line logging is being used.

Returns:: True if command line logging was enabled before this call.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetDebugMode (bool on)

Turn on debug mode.

Description:: Debug mode disables timeouts and timers. This makes debugging much easier.

Parameters:

on	Set to true to enable debugging mode.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetDomainName (cchar *s)

Set the application domain name string.

Parameters:

s	New value to use for the application domain name.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetEnv (cchar *key, cchar *value)

Set an environment variable value.

Parameters:

key	Variable name.
value	Variable value.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetExitStatus (int status)

Set the proposed exit status.

Description:: Set the exit status that can be retrieved via mprGetExitStatus

Parameters:

status

Proposed exit status value.

API Stability:: Prototype.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetExitTimeout (MprTicks timeout)

Set the exit timeout for a shutdown.

Description:: A shutdown waits for existing requests to complete before exiting. After this timeout has expired, the application will either invoke exit() or cancel the shutdown depending on whether MPR_EXIT_SAFE is defined in the exit strategy via mprShutdown. The default exit timeout is zero.

Parameters:

timeout

Time in milliseconds to wait for current requests to complete and the application to become idle.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetFilesLimit (int limit)

Set the maximum number of open file/socket descriptors.

Parameters:

limit

Limit to enforce.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetHostName (cchar *s)

Set the application host name string.

This is internal to the application and does not affect the O/S host name

Parameters:

s	New host name to use within the application.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

MprIdleCallback mprSetIdleCallback (MprIdleCallback idleCallback)

Define a new idle callback to be invoked by mprIsIdle()

Parameters:

idleCallback

Callback function to invoke to test if the application is idle.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetIpAddr (cchar *ip)

Sete the application IP address string.

Parameters:

ip	IP address string to store for the application.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetOsError (int error)

Set the O/S error code.

Description:: Set errno or equivalent.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSetServerName (cchar *s)

Set the application server name string.

Parameters:

s	New application server name to use within the application.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprShouldAbortRequests ()

Test if requests should be aborted.

Description:: This routine indicates that current requests should be terminated due to an application shutdown. This will be true then the MPR->state >= MPR_EXIT_STOPPED. See also mprShouldDenyNewRequests

Returns:: True if new requests should be denied.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

bool mprShouldDenyNewRequests ()

Test if new requests should be denied.

Description:: This routine indicates if an application shutdown has been initiated and services should not accept new requests or connections. This will be true then the MPR->state >= MPR_EXIT_STOPPING. See also mprShouldAbortRequests

Returns:: True if new requests should be denied.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprShutdown (int exitStrategy, int status, MprTicks timeout)

Initiate shutdown of the MPR and application.

Description:: Commence shutdown of the application according to the shutdown policy defined by the "exitStrategy" parameter. An application may call this routine from any thread to request the application exit. Depending on the exitStrategy, this may be an abortive or graceful exit. A desired application exit status code can defined to indicate the cause of the shutdown.

Once called, this routine will set the MPR execution state to MPR_EXIT_STOPPING. Services should detect this by calling mprShouldDenyNewRequests before accepting new connections or requests, but otherwise, services should not take any destructive actions until the MPR state is advanced to MPR_EXIT_STOPPED by mprDestroy. This state can be detected by calling mprShouldAbortRequests. Users can invoke mprCancelShutdown to resume normal operations provided mprDestroy has not proceeded past the point of no return when destructive termination actions are commenced.

Applications that have a user events thread and call mprServiceEvents from their main program, will typically invoke mprShutdown from some other MPR thread to initiate the shutdown. When running requests have completed, or when the shutdown timeout expires (MPR->exitTimeout), the call to mprServiceEvents in the main program will return and the application can then call mprDestroy to complete the shutdown.

Note: This routine starts the shutdown process but does not perform any destructive actions.

Parameters:

exitStrategy	Shutdown policy. If the MPR_EXIT_ABORT flag is specified, the application will immediately call exit() and will terminate without waiting for current requests to complete. This is not recommended for normal operation as data may be lost. If MPR_EXIT_SAFE is defined, the shutdown will be cancelled if all requests do not complete before the exit timeout defined via mprSetExitTimeout expires. Define the MPR_EXIT_RESTART flag for the application to automatically restart after exiting. Do not use this option if the application is using a watchdog/angel process to automatically restart the application (such as appman by appweb).
status	Proposed exit status to use when the application exits. See mprGetExitStatus
timeout	Exit timeout in milliseconds to wait for current requests to complete. If set to -1,.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

void mprSleep (MprTicks msec)

Sleep for a while.

Description:: This routine blocks for the given time and yields for GC during that time. Ensure all memory is held before the sleep.

Parameters:

msec	Number of milliseconds to sleep.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprStart ()

Start the Mpr services.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprStartEventsThread ()

Start an thread dedicated to servicing events.

This will create a new thread and invoke mprServiceEvents

Returns:: Zero if successful.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

int mprStartOsService ()

Start the O/S dependent subsystem.

API Stability:: Internal.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStopOsService, mprUriDecode, mprUriEncode

void mprStopOsService ()

Stop the O/S dependent subsystem.

API Stability:: Internal.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprUriDecode, mprUriEncode

char * mprUriDecode (cchar *uri)

Decode a URI string by de-scaping URI characters.

Description:: Decode a string with www-encoded characters that have meaning for URIs.

Parameters:

uri	URI to decode.

Returns:: A reference to the buf argument.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriEncode

char * mprUriDecodeInSitu (char *uri)

Decode a URI string by de-scaping URI characters.

Description:: Decode a string with www-encoded characters that have meaning for URIs. This routines operates in-situ and modifies the buffer.

Parameters:

uri	URI to decode.

Returns:: A reference to the buf argument.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

char * mprUriEncode (cchar *uri, int map)

Encode a string by escaping URI characters.

Description:: Encode a string escaping all characters that have meaning for URIs.

Parameters:

uri	URI to encode.
map	Map to encode characters. Select from MPR_ENCODE_URI or MPR_ENCODE_URI_COMPONENT.

Returns:: An allocated string containing the encoded URI.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode

MprBuf

Dynamic Buffer Module.

Description:: MprBuf is a flexible, dynamic growable buffer structure. It has start and end pointers to the data buffer which act as read/write pointers. Routines are provided to get and put data into and out of the buffer and automatically advance the appropriate start/end pointer. By definition, the buffer is empty when the start pointer == the end pointer. Buffers can be created with a fixed size or can grow dynamically as more data is added to the buffer.

For performance, the specification of MprBuf is deliberately exposed. All members of MprBuf are implicitly public. However, it is still recommended that wherever possible, you use the accessor routines provided.

See Also:: MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

API Stability:: Internal.

Fields:

ssize	buflen	Current size of buffer.
char *	data	Actual buffer for data.
char *	end	Pointer one past the last data chr.
char *	endbuf	Pointer one past the end of buffer.
ssize	growBy	Next growth increment to use.
ssize	maxsize	Max size the buffer can ever grow.
void *	refillArg	Refill arg - must be alloced memory.
MprBufProc	refillProc	Auto-refill procedure.
char *	start	Pointer to next data char.

void mprAddNullToBuf (MprBuf *buf)

Add a null character to the buffer contents.

Description:: Add a null byte but do not change the buffer content lengths. The null is added outside the "official" content length. This is useful when calling mprGetBufStart and using the returned pointer as a "C" string pointer.

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprAdjustBufEnd (MprBuf *buf, ssize count)

Adjust the buffer end position.

Description:: Adjust the buffer end position by the specified amount. This is typically used to advance the end position as content is appended to the buffer. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprPutBlock or mprPutChar routines, adjusting the end position is done automatically.

Parameters:

buf	Buffer created via mprCreateBuf.
count	Positive or negative count of bytes to adjust the end position.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprAdjustBufStart (MprBuf *buf, ssize count)

Adjust the buffer start position.

Description:: Adjust the buffer start position by the specified amount. This is typically used to advance the start position as content is consumed. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprGetBlock or mprGetChar routines, adjusting the start position is done automatically.

Parameters:

buf	Buffer created via mprCreateBuf.
count	Positive or negative count of bytes to adjust the start position.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

char * mprBufToString (MprBuf *buf)

Convert the buffer contents to a string.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Allocated string.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprCompactBuf (MprBuf *buf)

Compact the buffer contents.

Description:: Compact the buffer contents by copying the contents down to start the the buffer origin.

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

MprBuf * mprCreateBuf (ssize initialSize, ssize maxSize)

Create a new buffer.

Description:: Create a new buffer.

Parameters:

initialSize	Initial size of the buffer.
maxSize	Maximum size the buffer can grow to.

Returns:: A new buffer.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprFlushBuf (MprBuf *buf)

Flush the buffer contents.

Description:: Discard the buffer contents and reset the start end content pointers.

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprGetBlockFromBuf (MprBuf *buf, char *blk, ssize count)

Get a block of data from the buffer.

Description:: Get a block of data from the buffer start and advance the start position. If the requested length is greater than the available buffer content, then return whatever data is available.

Parameters:

buf	Buffer created via mprCreateBuf.
blk	Destination block for the read data.
count	Count of bytes to read from the buffer.

Returns:: The count of bytes read into the block or -1 if the buffer is empty.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

char * mprGetBuf (MprBuf *buf)

Get the origin of the buffer content storage.

Description:: Get a pointer to the start of the buffer content storage. This is always and allocated block.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: A pointer to the buffer content storage.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

char * mprGetBufEnd (MprBuf *buf)

Get a reference to the end of the buffer contents.

Description:: Get a pointer to the location immediately after the end of the buffer contents.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Pointer to the end of the buffer data contents. Points to the location one after the last data byte.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprGetBufLength (MprBuf *buf)

Get the buffer content length.

Description:: Get the length of the buffer contents. This is not the same as the buffer size which may be larger.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: The length of the content stored in the buffer in bytes.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

MprBufProc mprGetBufRefillProc (MprBuf *buf)

Get the buffer refill procedure.

Description:: Return the buffer refill callback function.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: The refill call back function if defined.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprGetBufSize (MprBuf *buf)

Get the current size of the buffer content storage.

Description:: This returns the size of the memory block allocated for storing the buffer contents.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: The size of the buffer content storage.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprGetBufSpace (MprBuf *buf)

Get the space available to store content.

Description:: Get the number of bytes available to store content in the buffer.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: The number of bytes available.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

char * mprGetBufStart (MprBuf *buf)

Get the start of the buffer contents.

Description:: Get a pointer to the start of the buffer contents. Use mprGetBufLength to determine the length of the content. Use mprGetBufEnd to get a pointer to the location after the end of the content.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Pointer to the start of the buffer data contents.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprGetCharFromBuf (MprBuf *buf)

Get a character from the buffer.

Description:: Get the next byte from the buffer start and advance the start position.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: The character or -1 if the buffer is empty.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprGrowBuf (MprBuf *buf, ssize count)

Grow the buffer.

Description:: Grow the storage allocated for content for the buffer. The new size must be less than the maximum limit specified via mprCreateBuf or mprSetBufSize

Parameters:

buf	Buffer created via mprCreateBuf.
count	Count of bytes by which to grow the buffer content size.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprInsertCharToBuf (MprBuf *buf, int c)

Insert a character into the buffer.

Description:: Insert a character into to the buffer prior to the current buffer start point.

Parameters:

buf	Buffer created via mprCreateBuf.
c	Character to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprLookAtLastCharInBuf (MprBuf *buf)

Peek at the last character in the buffer.

Description:: Non-destructively return the last character from just prior to the end position in the buffer. The character is returned and the end position is not altered.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprLookAtNextCharInBuf (MprBuf *buf)

Peek at the next character in the buffer.

Description:: Non-destructively return the next character from the start position in the buffer. The character is returned and the start position is not altered.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutBlockToBuf (MprBuf *buf, cchar *ptr, ssize size)

Put a block to the buffer.

Description:: Append a block of data to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
ptr	Block to append.
size	Size of block to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprPutCharToBuf (MprBuf *buf, int c)

Put a character to the buffer.

Description:: Append a character to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
c	Character to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutIntToBuf (MprBuf *buf, int64 i)

Put an integer to the buffer.

Description:: Append a integer to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
i	Integer to append to the buffer.

Returns:: Number of characters added to the buffer, otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutPadToBuf (MprBuf *buf, int c, ssize count)

Put padding characters to the buffer.

Description:: Append padding characters to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
c	Character to append.
count	Count of pad characters to put.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutStringToBuf (MprBuf *buf, cchar *str)

Put a string to the buffer.

Description:: Append a null terminated string to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
str	String to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutSubStringToBuf (MprBuf *buf, cchar *str, ssize count)

Put a substring to the buffer.

Description:: Append a null terminated substring to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
str	String to append.
count	Put at most count characters to the buffer.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutToBuf (MprBuf *buf, cchar *fmt, ...)

Put a formatted string to the buffer.

Description:: Format a string and append to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via mprCreateBuf.
fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprRefillBuf (MprBuf *buf)

Refill the buffer with data.

Description:: Refill the buffer by calling the refill procedure specified via mprSetBufRefillProc

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprResetBufIfEmpty (MprBuf *buf)

Reset the buffer.

Description:: If the buffer is empty, reset the buffer start and end pointers to the beginning of the buffer.

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprSetBufMax (MprBuf *buf, ssize maxSize)

Set the maximum buffer size.

Description:: Update the maximum buffer size set when the buffer was created.

Parameters:

buf	Buffer created via mprCreateBuf.
maxSize	New maximum size the buffer can grow to.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufRefillProc, mprSetBufSize

void mprSetBufRefillProc (MprBuf *buf, MprBufProc fn, void *arg)

Set the buffer refill procedure.

Description:: Define a buffer refill procedure. The MprBuf module will not invoke or manage this refill procedure. It is simply stored to allow upper layers to use and provide their own auto-refill mechanism.

Parameters:

buf	Buffer created via mprCreateBuf.
fn	Callback function to store.
arg	Callback data argument.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufSize

int mprSetBufSize (MprBuf *buf, ssize size, ssize maxSize)

Set the buffer size.

Description:: Set the current buffer content size and maximum size limit. Setting a current size will immediately grow the buffer to be this size. If the size is less than the current buffer size, the requested size will be ignored. ie. this call will not shrink the buffer. Setting a maxSize will define a maximum limit for how big the buffer contents can grow. Set either argument to -1 to be ignored.

Parameters:

buf	Buffer created via mprCreateBuf.
size	Size to immediately make the buffer. If size is less than the current buffer size, it will be ignored. Set to -1 to ignore this parameter.
maxSize	Maximum size the buffer contents can grow to.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc

MprCache

In-memory caching.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

API Stability:: Internal.

Fields:

MprTicks	lifespan	Default lifespan (msec).
ssize	maxKeys	Max number of keys.
ssize	maxMem	Max memory for session data.
MprMutex *	mutex	Cache lock.
int	resolution	Frequence for pruner.
struct MprCache *	shared	Shared common cache.
MprHash *	store	Key/value store.
MprEvent *	timer	Pruning timer.
ssize	usedMem	Memory in use for keys and data.

MprCache * mprCreateCache (int options)

Create a new cache object.

Parameters:

options

Set of option flags. Use MPR_CACHE_SHARED to select a global shared cache object.

Returns:: A cache instance object. On error, return null.

API Stability:: Evolving.

See Also:: mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

void * mprDestroyCache (MprCache *cache)

Destroy a new cache object.

Parameters:

cache

The cache instance object returned from mprCreateCache

API Stability:: Evolving.

See Also:: mprCreateCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

int mprExpireCacheItem (MprCache *cache, cchar *key, MprTicks expires)

Set the expiry date for a cache item.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key.
expires	Time when the cache item will expire. If expires is zero, the item is immediately removed from the cache.

Returns:: Zero if the expiry is successfully updated. Return MPR_ERR_CANT_FIND if the cache item is not present in the cache.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

void mprGetCacheStats (MprCache *cache, int *numKeys, ssize *mem)

Get the Cache statistics.

Parameters:

cache	The cache instance object returned from mprCreateCache
numKeys	Number of keys currently stored.
mem	Memory in use to store keys.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

int64 mprIncCache (MprCache *cache, cchar *key, int64 amount)

Increment a numeric cache item.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key.
amount	Numeric amount to increment the cache item. This may be a negative number to decrement the item.

Returns:: The new value for the cache item after incrementing.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

char * mprLookupCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Lookup an item in the cache.

Description:: Same as mprReadCache but will not update the last accessed time.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key.
modified	Optional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
version	Optional int64 value reference to receive the version number of the cache item. Set to null if not required. Cache items have a version number that is incremented every time the item is updated.

Returns:: The cache item value.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

void mprPruneCache (MprCache *cache)

Prune the cache.

Description:: Prune the cache and discard all cached items.

Parameters:

cache

The cache instance object returned from mprCreateCache

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

char * mprReadCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Read an item from the cache.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key.
modified	Optional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
version	Optional int64 value reference to receive the version number of the cache item. Set to null if not required. Cache items have a version number that is incremented every time the item is updated.

Returns:: The cache item value.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

bool mprRemoveCache (MprCache *cache, cchar *key)

Remove items from the cache.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key. If set to null, then remove all keys from the cache.

Returns:: True if the cache item was removed.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprSetCacheLimits, mprWriteCache

void mprSetCacheLimits (MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)

Set the cache resource limits.

Parameters:

cache	The cache instance object returned from mprCreateCache
keys	Set the maximum number of keys the cache can store.
lifespan	Set the default lifespan for cache items in milliseconds.
memory	Memory limit in bytes for all cache keys and items.
resolution	Set the cache item pruner resolution. This defines how frequently the cache manager will check items for expiration.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprWriteCache

int mprSetCacheLink (MprCache *cache, cchar *key, void *link)

Set a linked managed memory reference for a cached item.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key to write.
link	Managed memory reference. May be NULL.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

void mprSetCacheNotify (MprCache *cache, MprCacheProc notify)

Set a notification callback to be invoked for events of interest on cached items.

WARNING: the callback may happen on any thread. Use careful locking to synchronize access to data. Take care not to block the thread issuing the callback

Parameters:

cache	The cache instance object returned from mprCreateCache
notify	MprCacheProc notification callback. Invoked for events of interest on cache items. The event is set to MPR_CACHE_NOTIFY_REMOVE when items are removed from the cache. Invoked as:.

(*MprCacheProc)(MprCache *cache, cchar *key, cchar *data, int event);

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

ssize mprWriteCache (MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)

Write a cache item.

Parameters:

cache	The cache instance object returned from mprCreateCache
key	Cache item key to write.
value	Value to set for the cache item. This must be allocated memory.
modified	Value to set for the cache last modified time. If set to zero, the current time is obtained via mprGetTime
lifespan	Lifespan of the item in milliseconds. The item will be removed from the cache by the Cache manager when the lifetime expires unless it is rewritten to extend the lifespan.
version	Expected version number of the item. This is used to do transactional writes to the cache item. First the version number is retrieved via mprReadCache and that version number is supplied to mprWriteCache when the item is updated. If another caller updates the item in between the read/write, the version number will not match when the item is subsequently written and this call will fail with the MPR_ERR_BAD_STATE return code. Set to zero if version checking is not required.
options	Options to control how the item value is updated. Use MPR_CACHE_SET to update the cache item and create if it does not exist. Use MPR_CACHE_ADD to add the item only if it does not already exits. Use MPR_CACHE_APPEND to append the parameter value to any existing cache item value. Use MPR_CACHE_PREPEND to prepend the value.

Returns:: If writing the cache item was successful this call returns the number of bytes written. Otherwise a negative MPR error code is returned. MPR_ERR_BAD_STATE will be returned if an invalid version number is supplied. MPR_ERR_ALREADY_EXISTS will be returned if MPR_CACHE_ADD is specified and the cache item already exists.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits

MprCmd

Command execution Service.

Description:: The MprCmd service enables execution of local commands. It uses three full-duplex pipes to communicate read, write and error data with the command.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

API Stability:: Internal.

Fields:

int	argc	Count of args in argv.
cchar **	argv	List of args. Null terminated.
MprCmdProc	callback	Handler for client output and completion.
int	complete	All channels EOF and status gathered.
cchar **	defaultEnv	Environment to use if no env passed to mprStartCmd.
char *	dir	Current working dir for the process.
MprDispatcher *	dispatcher	Dispatcher to use for wait events.
MprList *	env	List of environment variables. Null terminated.
int	eofCount	Count of end-of-files.
MprCmdFile	files[MPR_CMD_MAX_PIPE]	Stdin, stdout for the command.
int	flags	Control flags (userFlags not here).
MprForkCallback	forkCallback	Forked client callback.
cchar **	makeArgv	Allocated argv.
MprMutex *	mutex	Multithread sync.
int	originalPid	Persistent copy of the pid.
int	pid	Process ID of the created process.
cchar *	program	Program path name.
int	requiredEof	Number of EOFs required for an exit.
char *	searchPath	Search path to use to locate the command.
MprSignal *	signal	Signal handler for SIGCHLD.
int	status	Command exit status.
MprBuf *	stderrBuf	Standard error output from the client.
MprBuf *	stdoutBuf	Standard output from the client.
int	stopped	Command stopped.
int	timedout	Request has timedout.
void *	userData	User data storage.
int	userFlags	User flags storage.

bool mprAreCmdEventsEnabled (MprCmd *cmd, int channel)

Return true if command events are enabled.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

Returns:: True if I/O events are enabled for the given channel.

API Stability:: Internal.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprCloseCmdFd (MprCmd *cmd, int channel)

Close the command channel.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

API Stability:: Stable.

See Also:: mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

MprCmd * mprCreateCmd (MprDispatcher *dispatcher)

Create a new Command object.

Returns:: A newly allocated MprCmd object.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprDestroyCmd (MprCmd *cmd)

Destroy the command.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprDisableCmdEvents (MprCmd *cmd, int channel)

Disable command I/O events.

This disables events on a given channel

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprDisconnectCmd (MprCmd *cmd)

Disconnect a command its underlying I/O channels.

This is used to prevent further I/O wait events while still preserving the MprCmd object

Parameters:

cmd	MprCmd object created via mprCreateCmd.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprEnableCmdEvents (MprCmd *cmd, int channel)

Enable command I/O events.

This enables events on a given channel

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprEnableCmdOutputEvents (MprCmd *cmd, bool on)

Enable command I/O events for the command's STDOUT and STDERR channels.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
on	Set to true to enable events. Set to false to disable.

Returns:: True if I/O events are enabled for the given channel.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprFinalizeCmd (MprCmd *cmd)

Finalize the writing of data to the command process.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

ssize mprGetActiveCmdCount ()

Get the count of active commands.

Description:: This is thread-safe with respect to MPR->state.

Returns:: Count of running commands.

API Stability:: Prototype.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

MprBuf * mprGetCmdBuf (MprCmd *cmd, int channel)

Get the underlying buffer for a channel.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

Returns:: A reference to the MprBuf buffer structure.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprGetCmdExitStatus (MprCmd *cmd)

Get the command exit status.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

Returns:: Status If the command has exited, a status between 0 and 255 is returned. Otherwise, a negative error code is returned.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprGetCmdFd (MprCmd *cmd, int channel)

Get the underlying file descriptor for an I/O channel.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

Returns:: The file descriptor.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

bool mprIsCmdRunning (MprCmd *cmd)

Test if the command is still running.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

Returns:: True if the command is still running.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprPollWinCmd (MprCmd *cmd, MprTicks timeout)

Poll for I/O on the command pipes.

This is only used on windows which can't adequately detect EOF on a named pipe

Parameters:

cmd	MprCmd object created via mprCreateCmd.
timeout	Time in milliseconds to wait for the command to complete and exit.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

ssize mprReadCmd (MprCmd *cmd, int channel, char *buf, ssize bufsize)

Make the I/O channels to send and receive data to and from the command.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
buf	Buffer to read into.
bufsize	Size of buffer.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprReapCmd (MprCmd *cmd, MprTicks timeout)

Reap the command.

This waits for and collect the command exit status

Parameters:

cmd	MprCmd object created via mprCreateCmd.
timeout	Time in milliseconds to wait for the command to complete and exit.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprRun (MprDispatcher *dispatcher, cchar *command, cchar *input, char **output, char **error, MprTicks timeout)

Run a simple blocking command using a string command line.

Parameters:

dispatcher	MprDispatcher event queue to use for waiting. Set to NULL to use the default MPR dispatcher.
command	Command line to run.
input	Command input. Data to write to the command which will be received on the comamnds stdin.
output	Reference to a string to receive the stdout from the command.
error	Reference to a string to receive the stderr from the command.
timeout	Time in milliseconds to wait for the command to complete and exit.

Returns:: Command exit status, or negative MPR error code.

API Stability:: Prototype.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprRunCmd (MprCmd *cmd, cchar *command, cchar **envp, cchar *in, char **out, char **err, MprTicks timeout, int flags)

Run a command using a string command line.

This starts the command via mprStartCmd() and waits for its completion

Parameters:

cmd	MprCmd object created via mprCreateCmd.
command	Command line to run.
envp	Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
in	Command input. Data to write to the command which will be received on the comamnds stdin.
out	Reference to a string to receive the stdout from the command.
err	Reference to a string to receive the stderr from the command.
timeout	Time in milliseconds to wait for the command to complete and exit.
flags	Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin MPR_CMD_OUT Capture stdout MPR_CMD_ERR Capture stderr MPR_CMD_EXACT_ENV Use the exact environment supplied. Don't inherit and blend with existing environment.

Returns:: Command exit status, or negative MPR error code.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprRunCmdV (MprCmd *cmd, int argc, cchar **argv, cchar **envp, cchar *in, char **out, char **err, MprTicks timeout, int flags)

Run a command using an argv[] array of arguments.

This invokes mprStartCmd() and waits for its completion

Parameters:

cmd	MprCmd object created via mprCreateCmd.
argc	Count of arguments in argv.
argv	Command arguments array.
envp	Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
in	Command input. Data to write to the command which will be received on the comamnds stdin.
out	Reference to a string to receive the stdout from the command.
err	Reference to a string to receive the stderr from the command.
timeout	Time in milliseconds to wait for the command to complete and exit.
flags	Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin MPR_CMD_OUT Capture stdout MPR_CMD_ERR Capture stderr.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdCallback (MprCmd *cmd, MprCmdProc callback, void *data)

Define a callback to be invoked to receive response data from the command.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
callback	Function of the signature MprCmdProc which will be invoked for receive notification for data from the commands stdout and stderr channels. MprCmdProc has the signature: int callback(MprCmd cmd, int channel, void data) {}.
data	User defined data to be passed to the callback.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdDefaultEnv (MprCmd *cmd, cchar **env)

Set the default environment to use for commands.

Description:: This environment is used if one is not defined via mprStartCmd

Parameters:

cmd	MprCmd object created via mprCreateCmd.
env	Array of environment "KEY=VALUE" strings. Null terminated.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdDir (MprCmd *cmd, cchar *dir)

Set the home directory for the command.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
dir	String directory path name.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdEnv (MprCmd *cmd, cchar **env)

Set the command environment.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
env	Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdSearchPath (MprCmd *cmd, cchar *search)

Set the default command search path.

Description:: The search path is used to locate the program to run for the command.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
search	Search string. This is in a format similar to the PATH environment variable.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprStartCmd (MprCmd *cmd, int argc, cchar **argv, cchar **envp, int flags)

Start the command.

This starts the command but does not wait for its completion. Once started, mprWriteCmd can be used to write to the command and response data can be received via mprReadCmd

Parameters:

cmd	MprCmd object created via mprCreateCmd.
argc	Count of arguments in argv.
argv	Command arguments array.
envp	Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
flags	Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprStopCmd (MprCmd *cmd, int signal)

Stop the command.

The command is immediately killed

Parameters:

cmd	MprCmd object created via mprCreateCmd.
signal	Signal to send to the command to kill if required.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprWaitForCmd (MprCmd *cmd, MprTicks timeout)

Wait for the command to complete.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
timeout	Time in milliseconds to wait for the command to complete and exit.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWriteCmd, mprWriteCmdBlock

ssize mprWriteCmd (MprCmd *cmd, int channel, cchar *buf, ssize bufsize)

Write data to an I/O channel.

Description:: This is a non-blocking write and may return having written less than requested.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
buf	Buffer to read into.
bufsize	Size of buffer.

Returns:: Count of bytes written.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdBlock

ssize mprWriteCmdBlock (MprCmd *cmd, int channel, cchar *buf, ssize bufsize)

Write data to an I/O channel.

Description:: This is a blocking write.

Parameters:

cmd	MprCmd object created via mprCreateCmd.
channel	Channel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
buf	Buffer to read into.
bufsize	Size of buffer.

Returns:: Count of bytes written.

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd

MprDispatcher

Event Dispatcher.

API Stability:: Internal.

Fields:

MprCond *	cond	Multi-thread sync.
MprEvent *	currentQ	Currently executing events.
MprEvent *	eventQ	Event queue.
int	flags	Dispatcher control flags.
cchar *	name	Dispatcher name / purpose.
struct MprDispatcher *	next	Next dispatcher linkage.
MprOsThread	owner	Owning thread of the dispatcher.
struct MprDispatcher *	parent	Queue pointer.
struct MprDispatcher *	prev	Previous dispatcher linkage.
struct MprEventService *	service	Event service reference.

void mprClearWaiting ()

Clear the event service waiting flag.

API Stability:: Evolving.

See Also:

MprDispatcher * mprCreateDispatcher (cchar *name, int flags)

Create a new event dispatcher.

Parameters:

name	Useful name for debugging.
flags	Dispatcher flags.

Returns:: A Dispatcher object that can manage events and be used with mprCreateEvent.

API Stability:: Internal.

See Also:

void mprDestroyDispatcher (MprDispatcher *dispatcher)

Disable a dispatcher from service events.

This removes the dispatcher from any dispatcher queues and allows it to be garbage collected

Parameters:

dispatcher

Dispatcher to disable.

API Stability:: Internal.

See Also:

MprDispatcher * mprGetDispatcher ()

Get the MPR primary dispatcher.

Returns:: The MPR dispatcher object.

API Stability:: Internal.

See Also:

int mprServiceEvents (MprTicks delay, int flags)

Service events.

Description:: This call services events on all dispatchers and services I/O events. An app should dedicate one and only one thread to be an event service thread. That thread should call mprServiceEvents from the top-level.

This call will service events until the timeout expires or if MPR_SERVICE_NO_BLOCK is specified in flags, until there are no more events to service. This routine will also return if the MPR has been instructed to terminate and is stopping. Calling mprServiceE

Application event code that is running off a dispatcher should never call mprServiceEvents recursively. Rather, the event code should call mprWaitForEvent if it needs to wait while servicing events on its own dispatcher.

Parameters:

delay	Time in milliseconds to wait. Set to zero for no wait. Set to -1 to wait forever.
flags	If set to MPR_SERVICE_NO_BLOCK, this call will service all due events without blocking. Otherwise set to zero.

Returns:: The number of events serviced. Returns MPR_ERR_BUSY is another thread is servicing events. Returns when the MPR is stopping or if the timeout expires or if MPR_SERVICE_NO_BLOCK is specified and there are no more events to service.

API Stability:: Stable.

See Also:

void mprSetEventServiceSleep (MprTicks delay)

Set the maximum sleep time for the event service.

Parameters:

delay

Maximum time to sleep before checking for events to service.

API Stability:: Evolving;.

See Also:

void mprSignalDispatcher (MprDispatcher *dispatcher)

Signal the dispatcher to wakeup and re-examine its queues.

Parameters:

dispatcher

Event dispatcher to monitor.

API Stability:: Internal.

See Also:

int mprWaitForEvent (MprDispatcher *dispatcher, MprTicks timeout)

Wait for an event to occur on the given dispatcher.

Description:: Use this routine to wait for an event and service the event on the given dispatcher. This routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.

Parameters:

dispatcher	Event dispatcher to monitor.
timeout	for waiting in milliseconds.

Returns:: Zero if successful and an event occurred before the timeout expired. Returns MPR_ERR_TIMEOUT if no event is fired before the timeout expires.

API Stability:: Stable.

See Also:

void mprWakeEventService ()

Wake the event service.

Description:: Used to wake the event service if an event is queued for service.

API Stability:: Stable.

See Also:

MprEvent

Event object.

Description:: The MPR provides a powerful priority based eventing mechanism. Events are described by MprEvent objects which are created and queued via mprCreateEvent. Each event may have a priority and may be one-shot or be continuously rescheduled according to a specified period. The event subsystem provides the basis for callback timers.

See Also:: MprDispatcher, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

API Stability:: Internal.

API Stability:: Internal.

Fields:

void *	data	Event private data.
struct MprDispatcher *	dispatcher	Event dispatcher service.
MprTicks	due	When is the event due.
int	flags	Event flags.
struct MprWaitHandler *	handler	Optional wait handler.
int	mask	I/O mask of events.
cchar *	name	Static debug name of the event.
struct MprEvent *	next	Next event linkage.
MprTicks	period	Reschedule period.
struct MprEvent *	prev	Previous event linkage.
MprEventProc	proc	Callback procedure.
void *	sock	Optional socket data.
MprTicks	timestamp	When was the event created.

MprEvent * mprCreateEvent (MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)

Create a new event.

Description:: Create a new event for service.

Parameters:

dispatcher	Dispatcher object created via mprCreateDispatcher.
name	Debug name of the event.
period	Time in milliseconds used by continuous events between firing of the event.
proc	Function to invoke when the event is run.
data	Data to associate with the event and stored in event->data. The data must be either an allocated memory object or MPR_EVENT_STATIC_DATA must be specified in flags.
flags	Flags to modify the behavior of the event. Valid values are: MPR_EVENT_CONTINUOUS to create an event which will be automatically rescheduled accoring to the specified period. Use MPR_EVENT_STATIC_DATA if the data argument does not point to an allocated memory object.

Returns:: The event object if successful.

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

int mprCreateEventOutside (MprDispatcher *dispatcher, cchar *name, void *proc, void *data, int flags)

Create an event from outside the MPR.

Description:: Create a new event when executing a non-MPR thread. This is the only safe way to invoke MPR services from a foreign-thread. The reason for this is that the MPR uses a cooperative garbage collector and an outside thread may call into the MPR at an inopportune time when the MPR is running the garbage collector which requires sole access to application memory.

This routine will create and queue the event and then return, unless MPR_EVENT_BLOCK is specified. In that case, this call will wait while the event callback proc runs to completion then this routine will return.

If you want to access MPR objects in the event callback, you may need to take steps to ensure they still exist when the event runs. This may mean calling mprAddRoot before creating the event and calling mprRemoveRoot inside the event callback.

While creating and queuing the event, this routine temporarily pauses the garbage collector. If the garbage collector is running, this call waits for it to complete before creating the event. This may necessitate a small delay before running the event.

NOTE: the event callback proc may run to completion before this function returns.

Parameters:

dispatcher	Dispatcher object created via mprCreateDispatcher Set to NULL for the MPR dispatcher. Use MPR_EVENT_QUICK in the flags to run the event on the events nonBlock dispatcher. This should only be used for quick, non-block event callbacks. If using another dispatcher, it is essential that the dispatcher not be destroyed while this event is queued or running. Such dispatchers must be retained before calling mprCallEventOutside via mprAddRoot or mprHold before using with this routine.
name	Descriptive event name. Does not need to be unique. Can be null.
proc	Callback function to invoke when the event is run.
data	Data to associate with the event and stored in event->data. The data must be non-MPR memory.
flags	Set to MPR_EVENT_BLOCK to invoke the callback and wait for its completion before returning. Include MPR_EVENT_QUICK to execute the event without creating using a worker. This should only be used for quick non-blocking event callback.s.

Returns:: Returns zero if successful, otherwise a negative MPR error code. Returns MPR_ERR_BAD_STATE if the MPR is stopping and the event cannot be created.

API Stability:: Evolving.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

MprEvent * mprCreateTimerEvent (MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)

Create a timer event.

Description:: Create and queue a timer event for service. This is a convenience wrapper to create continuous events over the mprCreateEvent call.

Parameters:

dispatcher	Dispatcher object created via mprCreateDispatcher
name	Debug name of the event.
proc	Function to invoke when the event is run.
period	Time in milliseconds used by continuous events between firing of the event.
data	Data to associate with the event and stored in event->data.
flags	Reserved. Must be set to zero.

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprEnableContinuousEvent (MprEvent *event, int enable)

Enable or disable an event being continous.

Description:: This call will modify the continuous property for an event.

Parameters:

event	Event object returned from mprCreateEvent
enable	Set to 1 to enable continous scheduling of the event.

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprRemoveEvent (MprEvent *event)

Remove an event.

Description:: Remove a queued event. This is useful to remove continuous events from the event queue.

Parameters:

event

Event object returned from mprCreateEvent

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprRescheduleEvent (MprEvent *event, MprTicks period)

Reschedule an event.

Description:: Reschedule a continuous event by modifying its period.

Parameters:

event	Event object returned from mprCreateEvent
period	Time in milliseconds used by continuous events between firing of the event.

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprRestartContinuousEvent (MprEvent *event)

Restart an event.

Description:: Restart a continuous event after it has been stopped via mprStopContinuousEvent. This call will add the event to the event queue and it will run after the configured event period has expired.

Parameters:

event

Event object returned from mprCreateEvent

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprStopContinuousEvent (MprEvent *event)

Stop an event.

Description:: Stop a continuous event and remove from the queue.

Parameters:

event

Event object returned from mprCreateEvent

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprWaitForEvent

MprFile

File I/O Module.

Description:: MprFile is the cross platform File I/O abstraction control structure. An instance will be created when a file is created or opened via mprOpenFile. Note: Individual files are not thread-safe and should only be used by one file.

API Stability:: Stable.

See Also:: mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

Fields:

int	attached	Attached to existing descriptor.
MprBuf *	buf	Buffer for I/O if buffered.
int	fd	File handle.
MprFileSystem *	fileSystem	File system owning this file.
MprRomInode *	inode	Reference to ROM file.
MprOff	iopos	Raw I/O position.
int	mode	File open mode.
char *	path	Filename.
int	perms	File permissions.
MprOff	pos	Current read position.
MprOff	size	Current file size.

MprFile * mprAttachFileFd (int fd, cchar *name, int omode)

Attach to an existing file descriptor.

Description:: Attach a file to an open file decriptor and return a file object.

Parameters:

fd	File descriptor to attach to.
name	Descriptive name for the file.
omode	Posix style file open mode mask. The open mode may contain the following mask values ored together: O_RDONLY Open read only O_WRONLY Open write only O_RDWR Open for read and write O_CREAT Create or re-create O_TRUNC Truncate O_BINARY Open for binary data O_TEXT Open for text data O_EXCL Open with an exclusive lock O_APPEND Open to append

Returns:: Returns an MprFile object to use in other file operations.

API Stability:: Stable.

See Also:: MprFile, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprCloseFile (MprFile *file)

Close a file.

Description:: This call closes a file without destroying the file object.

Parameters:

file	File instance returned from mprOpenFile

Returns:: Returns zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

void mprDisableFileBuffering (MprFile *file)

Disable file buffering.

Description:: Disable any buffering of data when using the buffer.

Parameters:

file	File instance returned from mprOpenFile

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprEnableFileBuffering (MprFile *file, ssize size, ssize maxSize)

Enable file buffering.

Description:: Enable data buffering when using the buffer.

Parameters:

file	File instance returned from mprOpenFile
size	Size to allocate for the buffer.
maxSize	Maximum size the data buffer can grow to.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprFlushFile (MprFile *file)

Flush any buffered write data.

Description:: Write buffered write data and then reset the internal buffers.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprGetFileChar (MprFile *file)

Read a character from the file.

Description:: Read a single character from the file and advance the read position.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.

Returns:: If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprGetFileFd (MprFile *file)

Get the file descriptor for a file.

Parameters:

file	File object returned via mprOpenFile

Returns:: An integer O/S file descriptor.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprOff mprGetFilePosition (MprFile *file)

Return the current file position.

Description:: Return the current read/write file position.

Parameters:

file	A file object returned from mprOpenFile

Returns:: The current file offset position if successful. Returns a negative MPR error code on errors.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprOff mprGetFileSize (MprFile *file)

Get the size of the file.

Description:: Return the current file size.

Parameters:

file	A file object returned from mprOpenFile

Returns:: The current file size if successful. Returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprFile * mprGetStderr ()

Return a file object for the Stderr I/O channel.

Returns:: A file object.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprFile * mprGetStdin ()

Return a file object for the Stdin I/O channel.

Returns:: A file object.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprFile * mprGetStdout ()

Return a file object for the Stdout I/O channel.

Returns:: A file object.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprFile * mprOpenFile (cchar *filename, int omode, int perms)

Open a file.

Description:: Open a file and return a file object.

Parameters:

filename	String containing the filename to open or create.
omode	Posix style file open mode mask. The open mode may contain the following mask values ored together: O_RDONLY Open read only O_WRONLY Open write only O_RDWR Open for read and write O_CREAT Create or re-create O_TRUNC Truncate O_BINARY Open for binary data O_TEXT Open for text data O_EXCL Open with an exclusive lock O_APPEND Open to append
perms	Posix style file permissions mask.

Returns:: Returns an MprFile object to use in other file operations.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprPeekFileChar (MprFile *file)

Non-destructively read a character from the file.

Description:: Read a single character from the file without advancing the read position.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.

Returns:: If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

ssize mprPutFileChar (MprFile *file, int c)

Write a character to the file.

Description:: Writes a single character to the file. Output is buffered and is flushed as required or when mprClose is called.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
c	Character to write.

Returns:: One if successful, otherwise returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

ssize mprPutFileString (MprFile *file, cchar *str)

Write a string to the file.

Description:: Writes a string to the file. Output is buffered and is flushed as required or when mprClose is called.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
str	String to write.

Returns:: The number of characters written to the file. Returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

ssize mprReadFile (MprFile *file, void *buf, ssize size)

Read data from a file.

Description:: Reads data from a file.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
buf	Buffer to contain the read data.
size	Size of buf in characters.

Returns:: The number of characters read from the file. Returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

char * mprReadLine (MprFile *file, ssize size, ssize *len)

Read a line from the file.

Description:: Read a single line from the file. Lines are delimited by the newline character. The newline is not included in the returned buffer. This call will read lines up to the given size in length. If no newline is found, all available characters, up to size, will be returned.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
size	Maximum number of characters in a line.
len	Pointer to an integer to hold the length of the returned string.

Returns:: An allocated string and sets *len to the number of bytes read.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

MprOff mprSeekFile (MprFile *file, int seekType, MprOff distance)

Seek the I/O pointer to a new location in the file.

Description:: Move the position in the file to/from which I/O will be performed in the file. Seeking prior to a read or write will cause the next I/O to occur at that location.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
seekType	Seek type may be one of the following three values: SEEK_SET Seek to a position relative to the start of the file SEEK_CUR Seek relative to the current position SEEK_END Seek relative to the end of the file
distance	A positive or negative byte offset.

Returns:: The new file position if successful otherwise a negative MPR error code is returned.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

int mprTruncateFile (cchar *path, MprOff size)

Truncate a file.

Description:: Truncate a file to a given size. Note this works on a path and not on an open file.

Parameters:

path	File to truncate.
size	New maximum size for the file.

Returns:: Zero if successful.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString

ssize mprWriteFile (MprFile *file, cvoid *buf, ssize count)

Write data to a file.

Description:: Writes data to a file.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
buf	Buffer containing the data to write.
count	Cound of characters in buf to write.

Returns:: The number of characters actually written to the file. Returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFileFmt, mprWriteFileString

ssize mprWriteFileFmt (MprFile *file, cchar *fmt, ...)

Write formatted data to a file.

Description:: Writes a formatted string to a file.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
fmt	Format string.

Returns:: The number of characters actually written to the file. Returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileString

ssize mprWriteFileString (MprFile *file, cchar *str)

Write a string to a file.

Description:: Writes a string to a file.

Parameters:

file	Pointer to an MprFile object returned via MprOpen.
str	String to write.

Returns:: The number of characters actually written to the file. Returns a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt

MprFileSystem

File system service.

Description:: The MPR provides a file system abstraction to support non-disk based file access such as flash or other ROM based file systems. The MprFileSystem structure defines a virtual file system interface that will be invoked by the various MPR file routines.

See Also:: MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

API Stability:: Internal.

Fields:

MprAccessFileProc	accessPath	Virtual access file routine.
bool	caseSensitive	Path comparisons are case sensitive.
MprCloseFileProc	closeFile	Virtual close file routine.
MprDeleteFileProc	deletePath	Virtual delete file routine.
MprGetPathInfoProc	getPathInfo	Virtual get file information routine.
MprGetPathLinkProc	getPathLink	Virtual get the symbolic link target.
bool	hasDriveSpecs	Paths can have drive specifications.
MprMakeDirProc	makeDir	Virtual make directory routine.
MprMakeLinkProc	makeLink	Virtual make link routine.
char *	newline	Newline for text files.
MprOpenFileProc	openFile	Virtual open file routine.
MprReadFileProc	readFile	Virtual read file routine.
cchar *	root	Root file path.
MprSeekFileProc	seekFile	Virtual seek file routine.
char *	separators	Filename path separators. First separator is the preferred separator.
MprSetBufferedProc	setBuffered	Virtual set buffered I/O routine.
MprTruncateFileProc	truncateFile	Virtual truncate file routine.
MprWriteFileProc	writeFile	Virtual write file routine.

void mprAddFileSystem (MprFileSystem *fs)

Create and initialize the disk FileSystem.

Description:: This is an internal routine called by the MPR during initialization.

Parameters:

fs	File system object.

API Stability:: Internal.

See Also:: MprRomInode, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

MprFileSystem * mprCreateFileSystem (cchar *path)

Create and initialize the FileSystem subsystem.

Description:: This is an internal routine called by the MPR during initialization.

Parameters:

path	Path name to the root of the file system.

Returns:: Returns a new file system object.

API Stability:: Internal.

See Also:: MprRomInode, mprAddFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

MprRomFileSystem * mprCreateRomFileSystem (cchar *path)

Create and initialize the ROM FileSystem.

Description:: This is an internal routine called by the MPR during initialization.

Parameters:

path	Path name to the root of the file system.

Returns:: Returns a new file system object.

API Stability:: Internal.

See Also:: MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

MprFileSystem * mprLookupFileSystem (cchar *path)

Lookup a file system.

Parameters:

path	Path representing a file in the file system.

Returns:: Returns a file system object.

API Stability:: Internal.

See Also:: MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

void mprSetPathNewline (cchar *path, cchar *newline)

Set the file system new line character string.

Parameters:

path	Path representing a file in the file system.
newline	String containing the newline character(s). "\\n". Windows uses "\\r\\n".

API Stability:: Stable.

See Also:: MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathSeparators, mprSetRomFileSystem

void mprSetPathSeparators (cchar *path, cchar *separators)

Set the file system path separators.

Parameters:

path	Path representing a file in the file system.
separators	String containing the directory path separators. Defaults to "/". Windows uses "/\/".

API Stability:: Stable.

See Also:: MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetRomFileSystem

int mprSetRomFileSystem (MprRomInode *inodeList)

Set the ROM file system data.

Description:: This defines the list of files present in the ROM file system. Use makerom to generate the inodeList data.

Parameters:

inodeList

Reference to the ROM file system list of files (inodes). This is generated by the makerom tool.

Returns:: Returns zero if successful.

API Stability:: Stable.

See Also:: MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators

MprFloat

Floating Point Services.

API Stability:: Stable.

See Also:: mprIsInfinite, mprIsNan, mprIsZero

API Stability:: Internal.

Fields:

int mprIsInfinite (double value)

Test if a double value is infinte.

Parameters:

value

Value to test.

Returns:: True if the value is +Infinity or -Infinity.

API Stability:: Stable.

See Also:: mprIsNan, mprIsZero

int mprIsNan (double value)

Test if a double value is not-a-number.

Parameters:

value

Value to test.

Returns:: True if the value is NaN.

API Stability:: Stable.

See Also:: mprIsInfinite, mprIsZero

int mprIsZero (double value)

Test if a double value is zero.

Parameters:

value

Value to test.

Returns:: True if the value is zero.

API Stability:: Stable.

See Also:: mprIsInfinite, mprIsNan

MprHash

Hash table entry structure.

Description:: The hash structure supports growable hash tables with high performance, collision resistant hashes. Each hash entry has a descriptor entry. This is used to manage the hash table link chains.

See Also:: MprHashProc, mprAddKey, mprAddKeyFmt, mprBlendHash, mprCloneHash, mprCreateHash, mprGetFirstKey, mprGetHashLength, mprGetNextKey, mprLookupKey, mprLookupKeyEntry, mprRemoveKey

API Stability:: Internal.

Fields:

MprKey **	buckets	Hash collision bucket table.
int	flags	Hash control flags.
MprHashProc	fn	Hash function.
int	length	Number of symbols in the table.
MprMutex *	mutex	GC marker sync.
int	size	Size of the buckets array.

MprKey * mprAddDuplicateKey (MprHash *table, cvoid *key, cvoid *ptr)

Add a duplicate symbol value into the hash table.

Description:: Add a symbol to the hash which may clash with an existing entry. Duplicate symbols can be added to the hash, but only one may be retrieved via mprLookupKey. To recover duplicate entries walk the hash using mprGetNextKey

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.
ptr	Arbitrary pointer to associate with the key in the table.

Returns:: Integer count of the number of entries.

API Stability:: Stable.

See Also:: MprHash

MprKey * mprAddKey (MprHash *table, cvoid *key, cvoid *ptr)

Add a symbol value into the hash table.

Description:: Associate an arbitrary value with a string symbol key and insert into the symbol table. This will replace existing key values. Use mprAddDuplicateKey to allow duplicates.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.
ptr	Arbitrary pointer to associate with the key in the table.

Returns:: Added MprKey reference.

API Stability:: Stable.

See Also:: MprHash

MprKey * mprAddKeyFmt (MprHash *table, cvoid *key, cchar *fmt, ...)

Add a key with a formatting value into the hash table.

Description:: Associate a formatted value with a key and insert into the symbol table.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.
fmt	Format string. See mprPrintf

Returns:: Integer count of the number of entries.

API Stability:: Stable.

See Also:: MprHash

MprKey * mprAddKeyWithType (MprHash *table, cvoid *key, cvoid *ptr, int type)

Add a symbol value into the hash table and set the key type.

Description:: Associate an arbitrary value with a string symbol key and insert into the symbol table.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.
ptr	Arbitrary pointer to associate with the key in the table.
type	Type of value.

Returns:: Added MprKey reference.

API Stability:: Internal.

See Also:: MprHash

MprHash * mprBlendHash (MprHash *target, MprHash *other)

Blend two hash tables.

Description:: Blend a hash table into a target hash.

Parameters:

target	Target hash to receive the properties from the other hash.
other	Hash to provide properties to blend.

Returns:: Returns target.

API Stability:: Stable.

See Also:: MprHash

MprHash * mprCloneHash (MprHash *table)

Copy a hash table.

Description:: Create a new hash table and copy all the entries from an existing table.

Parameters:

table

Symbol table returned via mprCreateSymbolTable.

Returns:: A new hash table initialized with the contents of the original hash table.

API Stability:: Stable.

See Also:: MprHash

MprHash * mprCreateHash (int hashSize, int flags)

Create a hash table.

Description:: Creates a hash table that can store arbitrary objects associated with string key values.

Parameters:

hashSize	Size of the hash table for the symbol table. Should be a prime number. Set to 0 or -1 to get a default (small) hash table.
flags	Table control flags. Use MPR_HASH_CASELESS for case insensitive comparisions, MPR_HASH_UNICODE if the hash keys are unicode strings, MPR_HASH_STATIC_KEYS if the keys are permanent and should not be managed for Garbage collection, and MPR_HASH_STATIC_VALUES if the values are permanent. MPR_HASH_STABLE to create an optimized list when the contents are stable or only accessed by one thread.

Returns:: Returns a pointer to the allocated symbol table.

API Stability:: Stable.

See Also:: MprHash

MprHash * mprCreateHashFromWords (cchar *str)

Create a hash of words.

Description:: Create a hash table of words from the given string. The hash key entry is the same as the key. The word separators are white space and comma.

Parameters:

str	String containing white space or comma separated words.

Returns:: Returns a hash of words.

API Stability:: Stable.

See Also:: MprHash

MprKey * mprGetFirstKey (MprHash *table)

Return the first symbol in a symbol entry.

Description:: Prepares for walking the contents of a symbol table by returning the first entry in the symbol table.

Parameters:

table

Symbol table returned via mprCreateSymbolTable.

Returns:: Pointer to the first entry in the symbol table.

API Stability:: Stable.

See Also:: MprHash

int mprGetHashLength (MprHash *table)

Return the count of symbols in a symbol entry.

Description:: Returns the number of symbols currently existing in a symbol table.

Parameters:

table

Symbol table returned via mprCreateSymbolTable.

Returns:: Integer count of the number of entries.

API Stability:: Stable.

See Also:: MprHash

MprKey * mprGetNextKey (MprHash *table, MprKey *last)

Return the next symbol in a symbol entry.

Description:: Continues walking the contents of a symbol table by returning the next entry in the symbol table. A previous call to mprGetFirstSymbol or mprGetNextSymbol is required to supply the value of the last argument.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
last	Symbol table entry returned via mprGetFirstSymbol or mprGetNextSymbol.

Returns:: Pointer to the first entry in the symbol table.

API Stability:: Stable.

See Also:: MprHash

char * mprHashKeysToString (MprHash *hash, cchar *join)

Convert hash keys to a single string.

Parameters:

hash	Hash pointer returned from mprCreateHash.
join	String to use as the element join string.

Returns:: String consisting of the joined hash keys.

API Stability:: Evolving.

See Also:: MprHash

char * mprHashToString (MprHash *hash, cchar *join)

Convert a hash of strings to a single string.

Parameters:

hash	Hash pointer returned from mprCreateHash.
join	String to use as the element join string.

Returns:: String consisting of the joined hash values.

API Stability:: Evolving.

See Also:: MprHash

void * mprLookupKey (MprHash *table, cvoid *key)

Lookup a symbol in the hash table.

Description:: Lookup a symbol key and return the value associated with that key.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.

Returns:: Value associated with the key when the entry was inserted via mprInsertSymbol.

API Stability:: Stable.

See Also:: MprHash

MprKey * mprLookupKeyEntry (MprHash *table, cvoid *key)

Lookup a symbol in the hash table and return the hash entry.

Description:: Lookup a symbol key and return the hash table descriptor associated with that key.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.

Returns:: MprKey for the entry.

API Stability:: Stable.

See Also:: MprHash

int mprRemoveKey (MprHash *table, cvoid *key)

Remove a symbol entry from the hash table.

Description:: Removes a symbol entry from the symbol table. The entry is looked up via the supplied key.

Parameters:

table	Symbol table returned via mprCreateSymbolTable.
key	String key of the symbole entry to delete.

Returns:: Returns zero if successful, otherwise a negative MPR error code is returned.

API Stability:: Stable.

See Also:: MprHash

MprJson

JSON Object.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

Fields:

struct MprJson *	children	Children properties.
int	length	Number of child properties.
cchar *	name	Property name for this object.
struct MprJson *	next	Next sibling.
struct MprJson *	prev	Previous sibling.
int	type	Property type. Object, Array or value.
cchar *	value	Property value - always strings.

int mprBlendJson (MprJson *dest, MprJson *other, int flags)

Blend two JSON objects.

Description:: This performs an N-level deep clone of the JSON object to be blended into the target object This will append arrays and add new object properties. If a primitive property already exists, it will only be updated if MPR_JSON_OVERWRITE is defined in flags.

Parameters:

dest	Parsed JSON object. This is the destination object. The "other" object will be blended into this object.
other	Parsed JSON object returned by mprJsonParser.
flags	Set to MPR_JSON_OVERWRITE to overwrite existing properties.

Returns:: Zero if successful.

API Stability:: Prototype.

See Also:: mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprCloneJson (MprJson *obj)

Clone a JSON object.

Description:: This does a deep copy of a JSON object tree. This copies all properties and their sub-properties.

Returns:: A new JSON object that replices the input object.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprCreateJson (int type)

Create a JSON object.

Parameters:

type	Set JSON object type to MPR_JSON_OBJ for an object, MPR_JSON_ARRAY for an array or MPR_JSON_VALUE for a value. Note: all values are stored as strings.

Returns:: JSON object.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprHash * mprDeserialize (cchar *str)

Deserialize a simple JSON string and return a hash of properties.

Parameters:

str	JSON string. This must be an object with one-level of properties.

Returns:: Hash of property values if successful, otherwise null.

API Stability:: Stable.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprHash * mprDeserializeInto (cchar *str, MprHash *hash)

Deserialize a simple JSON string into the given hash object.

Parameters:

str	JSON string. This must be an object with one-level of properties.
hash	Destination MprHash object.

Returns:: The supplied hash if successful. Otherwise null is returned.

API Stability:: Evolving.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

cchar * mprGetJson (MprJson *obj, cchar *key, int flags)

Lookup a JSON object tree for a string key value.

Description:: This routine is useful to querying leaf property values in a JSON object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to search for. This may include ".". For example: "settings.mode". See mprJsonQuery for a full description of key formats.
flags	Include MPR_JSON_SIMPLE for simple property names without embedded query expressions. Include MPR_JSON_TOP for properties at the top level (without embedded ".").

Returns:: A string property value or NULL if not found or not a string property type.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

ssize mprGetJsonLength (MprJson *obj)

Get the number of child properties in a JSON object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.

Returns:: The number of direct dependent child properties.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprGetJsonObj (MprJson *obj, cchar *key, int flags)

Lookup a parsed JSON object for a key value.

Parameters:

obj	Parsed JSON object returned by mprJsonParser.
key	Property name to search for. This may include ".". For example: "settings.mode". See mprJsonQuery for a full description of key formats.
flags	Include MPR_JSON_SIMPLE for simple property names without embedded query expressions. Include MPR_JSON_TOP for properties at the top level (without embedded ".").

Returns:: The property value as an object, otherwise NULL if not found or not the correct type. If MPR_JSON_TOP is specified in flags, the actual object reference is returned. Otherwise, a cloned copy of the object is returned.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprHashToJson (MprHash *hash)

Convert a hash object into a JSON object.

Parameters:

hash	MprHash object.

Returns:: An MprJson instance.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprHash * mprJsonToHash (MprJson *json)

Convert a JSON object into a Hash object.

Parameters:

json	JSON object tree.

Returns:: An MprHash instance.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

char * mprJsonToString (MprJson *obj, int flags)

Serialize a JSON object into a string.

Description:: Serializes a top level JSON object created via mprParseJson into a characters string in JSON format.

Parameters:

obj	Object returned via mprParseJson
flags	Serialization flags. Supported flags include MPR_JSON_PRETTY for a human-readable multiline format. MPR_JSON_QUOTES to wrap property names in quotes. Use MPR_JSON_STRINGS to emit all property values as quoted strings.

Returns:: Returns a serialized JSON character string.

API Stability:: Stable.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprLoadJson (cchar *path)

Load a JSON object from a filename.

Parameters:

path	Filename path containing a JSON string to load.

Returns:: JSON object tree.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

cchar * mprLookupJson (MprJson *obj, cchar *name)

Lookup a JSON object.

Description:: This is a low-level simple JSON property lookup routine. It does a one-level property lookup. Use mprQueryJson or mprGetJson to lookup properties that are not direct properties at the top level of the given object i.e. those that contain ".".

Parameters:

obj	Parsed JSON object returned by mprParseJson.
name	Name of the property to lookup.

Returns:: The property value as a string. Returns NULL if a matching property is not found.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprLookupJsonObj (MprJson *obj, cchar *name)

Lookup a JSON object.

Description:: This is a low-level simple JSON property lookup routine. This does a one-level property lookup and returns the actual JSON object and not a clone. Be careful with this API. Objects returned by this API cannot be modified or inserted into another JSON object with corrupting the original JSON object. Use mprQueryJson or mprGetJson to lookup properties and return a clone of the object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
name	Name of the property to lookup.

Returns:: The matching JSON object. Returns NULL if a matching property is not found.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprParseJson (cchar *str)

Parse a JSON string into an object tree.

Description:: Deserializes a JSON string created into an object. The top level of the JSON string must be an object, array, string, number or boolean value.

Parameters:

str	JSON string to deserialize.

Returns:: Returns a tree of MprJson objects. Each object represents a level in the JSON input stream.

API Stability:: Stable.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprParseJsonEx (cchar *str, MprJsonCallback *callback, void *data, MprJson *obj, cchar **errorMsg)

Extended JSON parsing from a JSON string into an object tree.

Description:: Parses a string into a tree of JSON objects This extended deserialization API takes callback functions to control how the object tree is constructed. The top level of the JSON string must be an object, array, string, number or boolean value.

Parameters:

str	JSON string to deserialize. This is an unmanaged reference. i.e. it will not be marked by the garbage collector.
callback	Callback functions. This is an instance of the MprJsonCallback structure.
data	Opaque object to pass to the given callbacks. This is an unmanaged reference.
obj	Optional object to serialize into.
errorMsg	Error message if the string fails to parse.

Returns:: Returns JSON object tree.

API Stability:: Internal.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprParseJsonInto (cchar *str, MprJson *obj)

Parse a JSON string into an existing object.

Description:: Deserializes a JSON string created into an object. The top level of the JSON string must be an object, array, string, number or boolean value.

Parameters:

str	JSON string to deserialize.
obj	JSON object to store parsed properties from str.

Returns:: The object passed in via "obj". This permits chaining.

API Stability:: Stable.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprQueryJson (MprJson *obj, cchar *key, int flags)

Query a parsed JSON object for a key value.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to search for. The property key may be a multipart property and may include . [] and ... substrings. For example: "settings.mode", "colors[2], users...name". The "." and "[]" operator reference sub-properties. The "..." elipsis operator spans zero or more objects levels. \ Inside the [] operator, you may include an expression to select qualifying properties. The expression is of the form: field OP value, where field is the name of the property, OP is ==, !=, <=, >= or ~. The latter being a simple string pattern match (contains). To compare the field iself, use "@". This is useful to compare array element values. For example: colors[@ == 'red'].
flags	Include MPR_JSON_SIMPLE for simple property names without embedded query expressions. Include MPR_JSON_TOP for properties at the top level (without embedded "."). Include MPR_JSON_DUPLICATE to permit duplicate values with the same property name.

Returns:: Returns a JSON list of matching properties.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

MprJson * mprRemoveJson (MprJson *obj, cchar *key)

Remove a property from a JSON object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to remove for. This may include ".". For example: "settings.mode". See mprJsonQuery for a full description of key formats.

Returns:: Returns a JSON object list of all removed properties.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

void mprRemoveJsonChild (MprJson *obj, MprJson *child)

Remove a child from a JSON object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
child	JSON child to remove.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

int mprSaveJson (MprJson *obj, cchar *path, int flags)

Save a JSON object to a filename.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
path	Filename path to contain the saved JSON string.
flags	Same flags as for mprJsonToString: MPR_JSON_PRETTY, MPR_JSON_QUOTES, MPR_JSON_STRINGS.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

char * mprSerialize (MprHash *hash, int flags)

Serialize a hash of properties as a JSON string.

Parameters:

hash	Hash of properties to examine.
flags	Serialization flags. Supported flags include MPR_JSON_PRETTY for a human-readable multiline format. MPR_JSON_QUOTES to wrap property names in quotes. Use MPR_JSON_STRINGS to emit all property values as quoted strings.

Returns:: JSON string.

API Stability:: Stable.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

int mprSetJson (MprJson *obj, cchar *key, cchar *value, int flags)

Update a key/value in the JSON object with a string value.

Description:: This call takes a multipart property name and will operate at any level of depth in the JSON object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to add/update. This may include ".". For example: "settings.mode". See mprJsonQuery for a full description of key formats.
flags	Include MPR_JSON_SIMPLE for simple property names without embedded query expressions. Include MPR_JSON_TOP for properties at the top level (without embedded "."). Include MPR_JSON_DUPLICATE to permit duplicate values with the same property name.
value	Character string value.

Returns:: Zero if updated successfully.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJsonError, mprSetJsonObj, mprTraceJson

void mprSetJsonError (MprJsonParser *jp, cchar *fmt, ...)

Signal a parse error in the JSON input stream.

Description:: JSON callback functions will invoke mprSetJsonError when JSON parse or data semantic errors are encountered. This routine may be called by the user JSON parse callback to emit a custom parse error notification.

Parameters:

jp	JSON control structure.
fmt	Printf style format string.
...	Printf arguments.

API Stability:: Evolving.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonObj, mprTraceJson

int mprSetJsonObj (MprJson *obj, cchar *key, MprJson *value, int flags)

Update a property in a JSON object.

Description:: This call takes a multipart property name and will operate at any level of depth in the JSON object.

Parameters:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to add/update. This may include ".". For example: "settings.mode". See mprJsonQuery for a full description of key formats.
value	Property value to set.
flags	Include MPR_JSON_SIMPLE for simple property names without embedded query expressions. Include MPR_JSON_TOP for properties at the top level (without embedded "."). Include MPR_JSON_DUPLICATE to permit duplicate values with the same property name.

Returns:: Zero if updated successfully.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprTraceJson

void mprTraceJson (int level, MprJson *obj)

Trace the JSON object to the debug log.

Parameters:

level	Debug trace level.
obj	Object to trace.

API Stability:: Prototype.

See Also:: mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj

MprList

List data structure.

Description:: The MprList is a dynamic, growable list suitable for storing pointers to arbitrary objects.

See Also:: MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

API Stability:: Internal.

Fields:

int	flags	Control flags.
void **	items	List item data.
int	length	Current length of the list contents.
int	maxSize	Maximum capacity.
MprMutex *	mutex	Multithread lock.
int	size	Current list capacity.

int mprAddItem (MprList *list, cvoid *item)

Add an item to a list.

Description:: Add the specified item to the list. The list must have been previously created via mprCreateList. The list will grow as required to store the item.

Parameters:

list	List pointer returned from mprCreateList
item	Pointer to item to store.

Returns:: Returns a positive list index for the inserted item. If the item cannot be inserted due to a memory allocation failure, -1 is returned.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprAddNullItem (MprList *list)

Add a null item to the list.

Description:: Add a null item to the list. This item does not count in the length returned by mprGetListLength and will not be visible when iterating using mprGetNextItem

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprAppendList (MprList *list, MprList *add)

Append a list.

Description:: Append the contents of one list to another. The list will grow as required to store the item.

Parameters:

list	List pointer returned from mprCreateList
add	List whose contents are added.

Returns:: Returns a pointer to the original list if successful. Returns NULL on memory allocation errors.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void mprClearList (MprList *list)

Clears the list of all items.

Description:: Resets the list length to zero and clears all items.

Parameters:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprCloneList (MprList *src)

Clone a list and all elements.

Description:: Copy the contents of a list into a new list.

Parameters:

src	Source list to copy.

Returns:: Returns a new list reference.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprCopyListContents (MprList *dest, MprList *src)

Copy list contents.

Description:: Copy the contents of a list into an existing list. The destination list is cleared first and has its dimensions set to that of the source clist.

Parameters:

dest	Destination list for the copy.
src	Source list.

Returns:: Returns zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprKeyValue * mprCreateKeyPair (cchar *key, cchar *value, int flags)

Create a key / value pair.

Description:: Allocate and initialize a key value pair for use by the MprList or MprHash modules.

Parameters:

key	Key string.
value	Key value string.
flags	Flags value.

Returns:: An initialized MprKeyValue

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprCreateList (int size, int flags)

Create a list.

Description:: Creates an empty list. MprList's can store generic pointers. They automatically grow as required when items are added to the list.

Parameters:

size	Initial capacity of the list. Set to < 0 to get a growable list with a default initial size. Set to 0 to to create the list but without any initial list storage. Then call mprSetListLimits to define the initial and maximum list size.
flags	Control flags. Possible values are: MPR_LIST_STATIC_VALUES to indicate list items are static and should not be marked for GC. MPR_LIST_STABLE to create an optimized list for private use that is not thread-safe.

Returns:: Returns a pointer to the list.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprCreateListFromWords (cchar *str)

Create a list of words.

Description:: Create a list of words from the given string. The word separators are white space and comma.

Parameters:

str	String containing white space or comma separated words.

Returns:: Returns a list of words.

API Stability:: Evolving.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetFirstItem (MprList *list)

Get the first item in the list.

Description:: Returns the value of the first item in the list. After calling this routine, the remaining list items can be walked using mprGetNextItem.

Parameters:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetItem (MprList *list, int index)

Get an list item.

Description:: Get an list item specified by its index.

Parameters:

list	List pointer returned from mprCreateList.
index	Item index into the list. Indexes have a range from zero to the lenghth of the list - 1.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetLastItem (MprList *list)

Get the last item in the list.

Description:: Returns the value of the last item in the list. After calling this routine, the remaining list items can be walked using mprGetPrevItem.

Parameters:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprGetListCapacity (MprList *list)

Get the current capacity of the list.

Description:: Returns the capacity of the list. This will always be equal to or greater than the list length.

Parameters:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprGetListLength (MprList *list)

Get the number of items in the list.

Description:: Returns the number of items in the list. This will always be less than or equal to the list capacity.

Parameters:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetNextItem (MprList *list, int *lastIndex)

Get the next item in the list.

Description:: Returns the value of the next item in the list. Before calling this routine, mprGetFirstItem must be called to initialize the traversal of the list.

Parameters:

list	List pointer returned from mprCreateList.
lastIndex	Pointer to an integer that will hold the last index retrieved.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetNextStableItem (MprList *list, int *lastIndex)

Get the next item in a stable list.

This is an optimized version of mprGetNextItem

Description:: Returns the value of the next item in the list. Before calling this routine, mprGetFirstItem must be called to initialize the traversal of the list.

Parameters:

list	List pointer returned from mprCreateList.
lastIndex	Pointer to an integer that will hold the last index retrieved.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetPrevItem (MprList *list, int *lastIndex)

Get the previous item in the list.

Description:: Returns the value of the previous item in the list. Before calling this routine, mprGetFirstItem and/or mprGetNextItem must be called to initialize the traversal of the list.

Parameters:

list	List pointer returned from mprCreateList.
lastIndex	Pointer to an integer that will hold the last index retrieved.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void mprInitList (MprList *list, int flags)

Initialize a list structure.

Description:: If a list is statically declared inside another structure, mprInitList can be used to initialize it before use.

Parameters:

list	Reference to the MprList struct.
flags	Control flags. Possible values are: MPR_LIST_STATIC_VALUES to indicate list items are static and should not be marked for GC. MPR_LIST_STABLE to create an optimized list for private use that is not thread-safe.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprInsertItemAtPos (MprList *list, int index, cvoid *item)

Insert an item into a list at a specific position.

Description:: Insert the item into the list before the specified position. The list will grow as required to store the item.

Parameters:

list	List pointer returned from mprCreateList
index	Location at which to store the item. The previous item at this index is moved up to make room.
item	Pointer to item to store.

Returns:: The position index (positive integer) if successful. If the item cannot be inserted due to a memory allocation failure, -1 is returned.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

char * mprListToString (MprList *list, cchar *join)

Convert a list of strings to a single string.

This uses the specified join string between the elements

Parameters:

list	List pointer returned from mprCreateList.
join	String to use as the element join string. May be null.

API Stability:: Evolving.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprLookupItem (MprList *list, cvoid *item)

Find an item and return its index.

Description:: Search for an item in the list and return its index.

Parameters:

list	List pointer returned from mprCreateList.
item	Pointer to value stored in the list.

Returns:: Positive list index if found, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprLookupStringItem (MprList *list, cchar *str)

Find a string item and return its index.

Description:: Search for the first matching string in the list and return its index.

Parameters:

list	List pointer returned from mprCreateList.
str	Pointer to string to look for.

Returns:: Positive list index if found, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprPopItem (MprList *list)

Pop an item.

Description:: Treat the list as a stack and pop the last pushed item.

Parameters:

list	List pointer returned from mprCreateList.

Returns:: The last pushed item. If the list is empty, returns NULL.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprPushItem (MprList *list, cvoid *item)

Push an item onto the list.

Description:: Treat the list as a stack and push the last pushed item.

Parameters:

list	List pointer returned from mprCreateList.
item	Item to push onto the list.

Returns:: Returns a positive integer list index for the inserted item. If the item cannot be inserted due to a memory allocation failure, -1 is returned.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveItem (MprList *list, cvoid *item)

Remove an item from the list.

Description:: Search for a specified item and then remove it from the list.

Parameters:

list	List pointer returned from mprCreateList.
item	Item pointer to remove.

Returns:: The positive index of the removed item, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveItemAtPos (MprList *list, int index)

Remove an item from the list.

Description:: Removes the element specified by index, from the list. The list index is provided by mprInsertItem.

Returns:: The positive index of the removed item, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveLastItem (MprList *list)

Remove the last item from the list.

Description:: Remove the item at the highest index position.

Parameters:

list	List pointer returned from mprCreateList.

Returns:: The positive index of the removed item, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveRangeOfItems (MprList *list, int start, int end)

Remove a range of items from the list.

Description:: Remove a range of items from the list. The range is specified from the start index up to and including the end index.

Parameters:

list	List pointer returned from mprCreateList.
start	Starting item index to remove (inclusive).
end	Ending item index to remove (inclusive).

Returns:: Returns zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveStringItem (MprList *list, cchar *str)

Remove a string item from the list.

Description:: Search for the first matching string and then remove it from the list.

Parameters:

list	List pointer returned from mprCreateList.
str	String value to remove.

Returns:: The positive index of the removed item, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprSetItem, mprSetListLimits, mprSortList

void * mprSetItem (MprList *list, int index, cvoid *item)

Set a list item.

Description:: Update the list item stored at the specified index.

Parameters:

list	List pointer returned from mprCreateList.
index	Location to update.
item	Pointer to item to store.

Returns:: The old item previously at that location index.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetListLimits, mprSortList

int mprSetListLimits (MprList *list, int initialSize, int maxSize)

Define the list size limits.

Description:: Define the list initial size and maximum size it can grow to.

Parameters:

list	List pointer returned from mprCreateList.
initialSize	Initial size for the list. This call will allocate space for at least this number of items.
maxSize	Set the maximum limit the list can grow to become.

Returns:: Returns zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSortList

void mprSort (void *base, ssize num, ssize width, MprSortProc compare, void *ctx)

Quicksort.

Description:: This is a quicksort with a context argument.

Parameters:

base	Base of array to sort.
num	Number of array elements.
width	Width of array elements.
compare	Comparison function.
ctx	Context argument to provide to comparison function.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprSortList (MprList *list, MprSortProc compare, void *ctx)

Sort a list.

Description:: Sort a list using the sort ordering dictated by the supplied compare function.

Parameters:

list	List pointer returned from mprCreateList.
compare	Comparison function. If null, then a default string comparison is used.
ctx	Context to provide to comparison function.

Returns:: The sorted list.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits

MprLog

Logging Services.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

API Stability:: Internal.

Fields:

void mprAssert (cchar *loc, cchar *msg)

Output an assure assertion failed message.

Description:: This will emit an assure assertion failed message to the standard error output. It may bypass the logging system.

Parameters:

loc	Source code location string. Use MPR_LOC to define a file name and line number string suitable for this parameter.
msg	Simple string message to output.

API Stability:: Stable.

See Also:: MprLogHandler, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

int mprBackupLog (cchar *path, int count)

Backup a log.

Parameters:

path	Base log filename.
count	Count of archived logs to keep.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprCreateLogService ()

Initialize the log service.

API Stability:: Internal.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprError (cchar *fmt, ...)

Log an error message.

Description:: Send an error message to the MPR debug logging subsystem. The message will be to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and log the message.

Parameters:

fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprFatal (cchar *fmt, ...)

Log a fatal error message and exit.

Description:: Send a fatal error message to the MPR debug logging subsystem and then exit the application by calling exit(). The message will be to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and log the message.

Parameters:

fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

struct MprFile * MprFile* mprGetLogFile ()

Get the log file object.

Description:: Returns the MprFile object used for logging.

Returns:: An MprFile object for logging.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

MprLogHandler mprGetLogHandler ()

Get the current MPR debug log handler.

Description:: Get the log handler defined via mprSetLogHandler

Returns:: A function of the signature MprLogHandler

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprInfo (cchar *fmt, ...)

Log an informational message.

Description:: Send an informational message to the MPR debug logging subsystem. The message will be to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and log the message.

Parameters:

fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprLog (int level, cchar *fmt, ...)

Write a message to the log file.

Description:: Send a message to the MPR logging subsystem. Logging support is enabled via the BIT_MPR_LOGGING define which is typically set via the Bit setting "logging: true". Logging typically is enabled in both debug and release builds. The mprLog function is a macro which translates into the mprLogProc function.

Parameters:

level	Logging level for this message. The level is 0-9 with zero being the most verbose.
fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

Remarks:: MprLog is highly useful as a debugging aid when integrating or when developing new modules.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprLogHeader ()

Emit a descriptive log header.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprRawLog (int level, cchar *fmt, ...)

Write a raw log message to the diagnostic log file.

Description:: Send a raw message to the MPR logging subsystem. Raw messages do not have any application prefix attached to the message and do not append a newline to the message.

Parameters:

level	Logging level for this message. The level is 0-9 with zero being the most verbose.
fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

Remarks:: MprLog is highly useful as a debugging aid when integrating or when developing new modules.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprSetLogBackup (ssize logSize, int backupCount, int flags)

Set the log rotation parameters.

Parameters:

logSize	If the size is zero, then the log file will be rotated on each application boot. Otherwise, the log file will be rotated if on application boot, the log file is larger than this size.
backupCount	Count of the number of log files to keep.
flags	Set to MPR_LOG_APPEND to append to existing log files. Set to MPR_LOG_TRUNCATE to truncate log files on application restart.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprSetLogLevel (int level)

Set the current logging level.

Description:: This call defines the maximum level of messages that will be logged. Calls to mprLog specify a message level. If the message level is greater than the defined logging level, the message is ignored.

Parameters:

level

New logging level. Must be 0-9 inclusive.

Returns:: The previous logging level.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprTrace, mprUsingDefaultLogHandler, mprWarn

int mprStartLogging (cchar *logSpec, int showConfig)

Start logging.

Parameters:

logSpec	Set the log file name and level. The format is "pathName[:level]". The following levels are generally observed: 0 - Essential messages, fatal errors and critical warnings 1 - Hard errors 2 - Configuration setup and soft warnings 3 - Useful informational messages 4 - Debug information 5-9 - Increasing levels of internal Appweb trace useful for debugging
showConfig	Set to true to log an initial system configuration.

Returns:: Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprTrace (int level, cchar *fmt, ...)

Write a trace message to the diagnostic log file.

Description:: Send a trace message to the MPR logging subsystem. Debug tracing support is enabled via the BIT_MPR_TRACING define which is typically set via the Bit setting "tracing: true". Tracing is typically is enabled in only debug builds. The mprTrace function is a macro which translates into the mprTraceProc function.

Description:: Sends a debug trace message to the MPR logging subsystem.

Parameters:

level	Logging level for this message. The level is 0-9 with zero being the most verbose.
fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

Remarks:: MprTrace is highly useful as a debugging aid when integrating or when developing new modules.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler, mprWarn

int mprUsingDefaultLogHandler ()

Determine if the app is using the default MPR log handler.

Description:: Returns true if no custom log handler has been installed.

Returns:: True if using the default log handler.

API Stability:: Evolving.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprWarn

void mprWarn (cchar *fmt, ...)

Log a warning message.

Description:: Send a warning message to the MPR debug logging subsystem. The message will be to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and log the message.

Parameters:

fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler

MprMem

Memory Allocation Service.

Description:: The MPR provides an application specific memory allocator to use instead of malloc. This allocator is tailored to the needs of embedded applications and is faster than most general purpose malloc allocators. It is deterministic and allocates and frees in constant time O(1). It exhibits very low fragmentation and accurate coalescing.

The allocator uses a garbage collector for freeing unused memory. The collector is a cooperative, non-compacting, parallel collector. The allocator is optimized for frequent allocations of small blocks (< 4K) and uses a scheme of free queues for fast allocation. Allocations are aligned as specified by BIT_MPR_ALLOC_ALIGN_SHIFT. This is typically 16 byte aligned for 64-bit systems and 8 byte aligned for 32-bit systems. The allocator will return unused memory back to the O/S to minimize application memory footprint.

The allocator handles memory allocation errors globally. The application may configure a memory limit so that memory depletion can be proactively detected and handled before memory allocations actually fail.

A memory block that is being used must be marked as active to prevent the garbage collector from reclaiming it. To mark a block as active, mprMark must be called during each garbage collection cycle. When allocating non-temporal memory blocks, a manager callback can be specified via mprAllocObj. This manager routine will be called by the collector so that dependent memory blocks can be marked as active.

The collector performs the marking phase by invoking the manager routines for a set of root blocks. A block can be added to the set of roots by calling mprAddRoot. Each root's manager routine will mark other blocks which will cause their manager routines to run and so on, until all active blocks have been marked. Non-marked blocks can then safely be reclaimed as garbage. A block may alternatively be permanently marked as active by calling mprHold.

The mark phase begins when all threads explicitly "yield" to the garbage collector. This cooperative approach ensures that user threads will not inadvertendly loose allocated blocks to the collector. Once all active blocks are marked, user threads are resumed and the garbage sweeper frees unused blocks in parallel with user threads.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

Fields:

uchar	eternal	Immune from GC. Implemented as a byte to be atomic.
uchar	first	Block is first block in region.
uchar	free	Block not in use.
uchar	fullRegion	Block is an entire region - never on free queues.
uchar	hasManager	Has manager function. Set at block init.
uchar	mark	GC mark indicator. Toggled for each GC pass by mark() when thread yielded.
uchar	qindex	Freeq index. Always less than 512 queues.
MprMemSize	size	Size in bytes. This is a 32-bit quantity on all systems unless BIT_MPR_ALLOC_BIG is defined and then it will be 64 bits.

void mprAddRoot (cvoid *ptr)

Add a memory block as a root for garbage collection.

Description:: Remove the root when no longer required via mprAddRoot

Parameters:

ptr	Any memory pointer.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprAlloc (size_t size)

Allocate a block of memory.

Description:: Allocates a block of memory of the required size. The memory is not zeroed.

Parameters:

size	Size of the memory block to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprAllocMem (size_t size, int flags)

Allocate a block of memory.

Description:: This is the lowest level of memory allocation routine. Memory is freed via the garbage collector. To protect an active memory block memory block from being reclaimed, it must have a reference to it. Memory blocks can specify a manager routine via mprAllocObj. The manager is is invoked by the garbage collector to "mark" dependant active blocks. Marked blocks will not be reclaimed by the garbage collector.

Parameters:

size	Size of the memory block to allocate.
flags	Allocation flags. Supported flags include: MPR_ALLOC_MANAGER to reserve room for a manager callback and MPR_ALLOC_ZERO to zero allocated memory.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprAllocObj (Type type, MprManager manager)

Allocate an object of a given type.

Description:: Allocates a zeroed block of memory large enough to hold an instance of the specified type with a manager callback. This call associates a manager function with an object that will be invoked when the object is freed or the garbage collector needs the object to mark internal properties as being used. This call is implemented as a macro.

Parameters:

type	Type of the object to allocate.
manager	Manager function to invoke when the allocation is managed.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprAllocZeroed (size_t size)

Allocate a zeroed block of memory.

Description:: Allocates a zeroed block of memory.

Parameters:

size	Size of the memory block to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

struct Mpr * Mpr* mprCreateMemService (MprManager manager, int flags)

Create and initialize the Memory service.

Description:: Called internally by the MPR. Should not be called by users.

Parameters:

manager	Memory manager to manage the Mpr object.
flags	Memory initialization control flags.

Returns:: The Mpr control structure.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

bool mprEnableGC (bool on)

Enable or disable the garbage collector.

Parameters:

on	Set to one to enable and zero to disable.

Returns:: Returns one if the collector was previously enabled. Otherwise returns zero.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

int mprGC (int flags)

Collect garbage.

Description:: Initiates garbage collection to free unreachable memory blocks. It is normally not required for users to invoke this routine as the garbage collector will be scheduled as required. If the MPR_GC_NO_BLOCK is not specified, this routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.

Parameters:

flags

Flags to control the collection. Set flags to MPR_GC_FORCE to force a collection. Set to MPR_GC_DEFAULT to perform a conditional sweep where the sweep is only performed if there is sufficient garbage to warrant a collection. Set to MPR_GC_NO_BLOCK to run GC if necessary and return without yielding. Use MPR_GC_COMPLETE to force a GC and wait until the GC cycle fully completes including the sweep phase.

Returns:: The number of blocks freed on the last GC sweep. If using MPR_GC_NO_BLOCK, this may be the result from a prior GC sweep.

API Stability:: Evolving.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

size_t mprGetBlockSize (cvoid *ptr)

Get the allocated size of a memory block.

Parameters:

ptr	Any memory allocated by mprAlloc.

Returns:: The block size in bytes.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

size_t mprGetMem ()

Return the amount of memory currently used by the application.

On Unix, this returns the total application memory size including code, stack, data and heap. On Windows, VxWorks and other operatings systems, it returns the amount of allocated heap memory

Returns:: The amount of memory used by the application in bytes.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

MprMemStats * mprGetMemStats ()

Return the current allocation memory statistics block.

Returns:: A reference to the allocation memory statistics. Do not modify its contents.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

int mprGetPageSize ()

Get the current O/S virtual page size.

Returns:: The page size in bytes.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

bool mprHasMemError ()

Determine if the MPR has encountered memory allocation errors.

Description:: Returns true if the MPR has had a memory allocation error. Allocation errors occur if any memory allocation would cause the application to exceed the configured warnHeap limit, or if any O/S memory allocation request fails.

Returns:: TRUE if a memory allocation error has occurred. Otherwise returns FALSE.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprHold (cvoid *ptr)

Hold a memory block.

Description:: This call will protect a memory block from freeing by the garbage collector. Call mprRelease to allow the block to be collected.

Parameters:

ptr	Any memory block.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprHoldBlocks (cvoid *ptr, ...)

Hold memory blocks.

Description:: This call will protect a set of memory blocks from freeing by the garbage collector. Call mprReleaseBlocks to allow the blocks to be collected.

Parameters:

ptr	Any memory block.
...	Other memory blocks. Terminate the list with a NULL.

API Stability:: Prototype.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

int mprIsValid (cvoid *ptr)

Test is a pointer is a valid memory context.

This is used to test if a block has been dynamically allocated

Parameters:

ptr	Any memory context allocated by mprAlloc or mprCreate.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

int mprMemcmp (cvoid *b1, size_t b1Len, cvoid *b2, size_t b2Len)

Compare two byte strings.

Description:: Safely compare two byte strings. This is a safe replacement for memcmp.

Parameters:

b1	Pointer to the first byte string.
b1Len	Length of the first byte string.
b2	Pointer to the second byte string.
b2Len	Length of the second byte string.

Returns:: Returns zero if the byte strings are identical. Otherwise returns -1 if the first string is less than the second. Returns 1 if the first is greater than the first.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

size_t mprMemcpy (void *dest, size_t destMax, cvoid *src, size_t nbytes)

Safe copy for a block of data.

Description:: Safely copy a block of data into an existing memory block. The call ensures the destination block is not overflowed and returns the size of the block actually copied. This is similar to memcpy, but is a safer alternative.

Parameters:

dest	Pointer to the destination block.
destMax	Maximum size of the destination block.
src	Block to copy.
nbytes	Size of the source block.

Returns:: The number of characters in the allocated block.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprMemdup (cvoid *ptr, size_t size)

Duplicate a block of memory.

Description:: Copy a block of memory into a newly allocated block.

Parameters:

ptr	Pointer to the block to duplicate.
size	Size of the block to copy.

Returns:: Returns an allocated block.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

bool mprPauseGC ()

Pause the garbage collector.

Description:: This call pause garbage collection so that all thread variables will be safe from collection. It is useful to prevent collection when calling a routine that is known to yield. This routine increments a pause counter and mprResumeGC will decrement. Garbage collection can resume when the counter is zero.

It is essential that mprResumeGC is always invoked after mprPauseGC. Be very careful to ensure that all error code paths call mprResumeGC as required.

To be effective, this routine also pauses any MPR shutdown.

Returns:: True if GC and MPR shutdown can be paused. Will return false if the MPR is stopping and GC cannot be paused.

API Stability:: Prototype.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprPrintMem (cchar *msg, int flags)

Print a memory usage report to stdout.

Parameters:

msg	Prefix message to the report.
flags	Set to MPR_MEM_DETAIL for a detailed memory report.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprRealloc (void *ptr, size_t size)

Reallocate a block.

Description:: Reallocates a block increasing its size. If the specified size is less than the current block size, the call will ignore the request and simply return the existing block. The memory is zeroed.

Parameters:

ptr	Memory to reallocate. If NULL, call malloc.
size	New size of the required memory block.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to realloc and mprRealloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprRelease (cvoid *ptr)

Release a memory block.

Description:: This call is used to allow a memory block to be freed by the garbage collector after calling mprHold.

Parameters:

ptr	Any memory block.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprReleaseBlocks (cvoid *ptr, ...)

Release a memory blocks.

Description:: This call is used to allow a memory blocks to be freed by the garbage collector after calling mprHoldBlocks.

Parameters:

ptr	Any memory block.
...	Other memory blocks. Terminate the list with a NULL.

API Stability:: Prototype.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprRemoveRoot (cvoid *ptr)

Remove a memory block as a root for garbage collection.

Description:: The memory block should have previously been added as a root via mprAddRoot

Parameters:

ptr	Any memory pointer.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprResetMemError ()

Reset the memory allocation error flag.

Description:: Reset the alloc error flag triggered.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprResumeGC ()

Resume the garbage collector.

Description:: This call pause garbage collection so that all thread variables will be safe from collection. This routine increments a pause counter and mprReleaseGC will decrement. Garbage collection can resume when the counter is zero. This also resumes any shutdown capability for the application.

API Stability:: Prototype.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * mprSetManager (void *ptr, MprManager manager)

Update the manager for a block of memory.

Description:: This call updates the manager for a block of memory allocated via mprAllocWithManager.

Parameters:

ptr	Memory to free. If NULL, take no action.
manager	Manager function to invoke when the memory is released.

Returns:: The original object.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprSetMemError ()

Set an memory allocation error condition on a memory context.

This will set an allocation error condition on the given context and all its parents. This way, you can test the ultimate parent and detect if any memory allocation errors have occurred

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprSetMemLimits (ssize warnHeap, ssize maximum, ssize cache)

Configure the application memory limits.

Description:: Configure memory limits to constrain memory usage by the application. The memory allocation subsystem will check these limits before granting memory allocation requrests. The warnHeap is a soft limit that if exceeded will invoke the memory allocation callback, but will still honor the request. The maximum limit is a hard limit. The MPR will prevent allocations which exceed this maximum. The memory callback handler is defined via the mprCreate call.

Parameters:

warnHeap	Soft memory limit. If exceeded, the request will be granted, but the memory handler will be invoked. to issue a warning and potentially take remedial acation. If -1, then do not update the warnHeap.
maximum	Hard memory limit. If exceeded, the request will not be granted, and the memory handler will be invoked. If -1, then do not update the maximum.
cache	Heap cache. Try to keep at least this amount of memory in the heap free queues If -1, then do not update the cache.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprSetMemNotifier (MprMemNotifier cback)

Define a memory notifier.

Description:: A notifier callback will be invoked for memory allocation errors for the given memory context.

Parameters:

cback

Notifier callback function.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void mprSetMemPolicy (int policy)

Set the memory allocation policy for when allocations fail.

Parameters:

policy

Set to MPR_ALLOC_POLICY_EXIT for the application to immediately exit on memory allocation errors. Set to MPR_ALLOC_POLICY_RESTART to restart the appplication on memory allocation errors.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprVirtAlloc, mprVirtFree

void * mprVirtAlloc (size_t size, int mode)

Memory virtual memory into the applications address space.

Parameters:

size	of virtual memory to map. This size will be rounded up to the nearest page boundary.
mode	Mask set to MPR_MAP_READ \| MPR_MAP_WRITE.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtFree

void mprVirtFree (void *ptr, size_t size)

Free (unpin) a mapped section of virtual memory.

Parameters:

ptr	Virtual address to free. Should be page aligned.
size	Size of memory to free in bytes.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc

void * palloc (size_t size)

Allocate a "permanent" block of memory that is not subject GC.

Description:: This allocates a block of memory using the MPR allocator. It then calls mprHold on the block. to prevent GC from freeing the block.

Parameters:

size	Size of the memory block to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to palloc and malloc.

API Stability:: Evolving.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void pfree (void *ptr)

Free a "permanent" block of memory allocated via "palloc".

Description:: This releases a block of memory allocated via "palloc" to be collected by the garbage collector.

Parameters:

ptr	Pointer to the block.

Remarks:: Do not mix calls to pfree and free.

API Stability:: Evolving.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

void * prealloc (void *ptr, size_t size)

Reallocate a "permanent" block of memory allocated via "palloc".

Description:: This increases the size of a block of memory allocated via "palloc".

Parameters:

ptr	Pointer to the block.
size	New block size.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:: Do not mix calls to prealloc and malloc.

API Stability:: Evolving.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

size_t psize (void *ptr)

Return the size of the block.

This may be larger than what was originally requested

Parameters:

ptr	Pointer to the block.

Returns:: Size of the allocated block.

API Stability:: Evolving.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

MprMime

Mime Type hash table entry (the URL extension is the key).

API Stability:: Stable.

See Also:: mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprLookupMime, mprSetMimeProgram

API Stability:: Internal.

Fields:

char *		program	Mime type string.
char *		type	Mime type string.

MprMime * mprAddMime (MprHash *table, cchar *ext, cchar *mimeType)

Add a mime type to the mime type table.

Parameters:

table	type hash table returned by mprCreateMimeTypes
ext	Filename extension to use as a key for the given mime type.
mimeType	Mime type string to associate with the ext key.

Returns:: Mime type entry object. This is owned by the mime type table.

API Stability:: Stable.

See Also:: MprMime, mprCreateMimeTypes, mprGetMimeProgram, mprLookupMime, mprSetMimeProgram

MprHash * mprCreateMimeTypes (cchar *path)

Create the mime types.

Parameters:

path	Filename of a mime types definition file.

Returns:: Hash table of mime types keyed by file extension.

API Stability:: Stable.

See Also:: MprMime, mprAddMime, mprGetMimeProgram, mprLookupMime, mprSetMimeProgram

cchar * mprGetMimeProgram (MprHash *table, cchar *mimeType)

Get the mime type program for a given mimeType.

Parameters:

table	type hash table returned by mprCreateMimeTypes
mimeType	Mime type to update.

Returns:: The program name associated with this mime type.

API Stability:: Stable.

See Also:: MprMime, mprAddMime, mprCreateMimeTypes, mprLookupMime, mprSetMimeProgram

cchar * mprLookupMime (MprHash *table, cchar *ext)

Get the mime type for an extension.

This call will return the mime type from a limited internal set of mime types for the given path or extension

Parameters:

table	Hash table of mime types to examine.
ext	Path or extension to examine.

Returns:: Mime type string. Returns null if mime type is not known.

API Stability:: Stable.

See Also:: MprMime, mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprSetMimeProgram

int mprSetMimeProgram (MprHash *table, cchar *mimeType, cchar *program)

Set the mime type program.

Parameters:

table	type hash table returned by mprCreateMimeTypes
mimeType	Mime type to update.
program	Program name to associate with this mime type.

Returns:: Zero if the update is successful. Otherwise return MPR_ERR_CANT_FIND if the mime type is not present in the mime type table.

API Stability:: Stable.

See Also:: MprMime, mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprLookupMime

MprModule

Loadable Module Service.

Description:: The MPR provides services to load and unload shared libraries.

See Also:: MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

API Stability:: Stable.

API Stability:: Internal.

Fields:

char *	entry	Module library init entry point.
int	flags	Module control flags.
void *	handle	O/S shared library load handle.
MprTicks	lastActivity	When the module was last used.
MprTime	modified	When the module file was last modified.
void *	moduleData	Module specific data - must be alloced data.
char *	name	Unique module name.
char *	path	Module library filename.
MprModuleProc	start	Start the module.
MprModuleProc	stop	Stop the module. Should be unloadable after stopping.
MprTicks	timeout	Inactivity unload timeout.

MprModule * mprCreateModule (cchar *name, cchar *path, cchar *entry, void *data)

Create a module.

Description:: This call will create a module object for a loadable module. This should be invoked by the module itself in its module entry point to register itself with the MPR.

Parameters:

name	Name of the module.
path	Optional filename of a module library to load. When loading, the filename will be searched using the defined module search path (see mprSetModuleSearchPath). The filename may or may not include a platform specific shared library extension such as .dll, .so or .dylib. By omitting the library extension, code can portably load shared libraries.
entry	Name of function to invoke after loading the module.
data	Arbitrary data pointer. This will be defined in MprModule.data and passed into the module initialization entry point.

Returns:: A module object for this module.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

cchar * mprGetModuleSearchPath ()

Get the module search path.

Description:: Get the directory search path used by the MPR when loading dynamic modules. This is a colon separated (or semicolon on Windows) set of directories.

Returns:: The module search path.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprLoadModule (MprModule *mp)

Load a module.

Description:: Load a module library. This will load a dynamic shared object (shared library) and call the modules library entry point. If the module is already loaded, this call will do nothing.

Parameters:

mp	Module object created via mprCreateModule

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprLoadNativeModule (MprModule *mp)

Load a native module.

Parameters:

mp	Module object created via mprCreateModule

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

MprModule * mprLookupModule (cchar *name)

Lookup a module.

Description:: Lookup a module by name and return the module object.

Parameters:

name	Name of the module specified to mprCreateModule

Returns:: A module object for this module created in the module entry point by calling mprCreateModule

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void * mprLookupModuleData (cchar *name)

Lookup a module and return the module data.

Description:: Lookup a module by name and return the module specific data defined via mprCreateModule

Parameters:

name	Name of the module specified to mprCreateModule

Returns:: The module data.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

char * mprSearchForModule (cchar *module)

Search for a module on the current module path.

Parameters:

module

Name of the module to locate.

Returns:: A string containing the full path to the module. Returns NULL if the module filename cannot be found.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void mprSetModuleFinalizer (MprModule *module, MprModuleProc stop)

Define a module finalizer that will be called before a module is stopped.

Parameters:

module	Module object to modify.
stop	Callback function to invoke before stopping the module.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void mprSetModuleSearchPath (char *searchPath)

Set the module search path.

Description:: Set the directory search path used by the MPR when loading dynamic modules. This path string must should be a colon separated (or semicolon on Windows) set of directories.

Parameters:

searchPath

Colon separated set of directories.

Returns:: The module search path.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void mprSetModuleTimeout (MprModule *module, MprTicks timeout)

Set a module timeout.

Parameters:

module	Module object to modify.
timeout	Inactivity timeout in milliseconds before unloading the module.

API Stability:: Internal.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprStartModule (MprModule *mp)

Start a module.

Description:: Invoke the module start entry point. The start routine is only called once.

Parameters:

mp	Module object returned via mprLookupModule

API Stability:: Internal.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprStopModule (MprModule *mp)

Stop a module.

Description:: Invoke the module stop entry point. The stop routine is only called once.

Parameters:

mp	Module object returned via mprLookupModule

API Stability:: Internal.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprUnloadModule, mprUnloadNativeModule

int mprUnloadModule (MprModule *mp)

Unload a module.

Description:: Unload a module from the MPR. This will unload a dynamic shared object (shared library). This routine is not fully supported by the MPR and is often fraught with issues. A module must usually be completely inactive with no allocated memory when it is unloaded. USE WITH CARE.

Parameters:

mp	Module object returned via mprLookupModule

Returns:: Zero if the module can be unloaded. Otherwise a negative MPR error code.

API Stability:: Internal.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadNativeModule

int mprUnloadNativeModule (MprModule *mp)

Unload a native module.

Description:: WARNING: modules must be designed to be unloaded and must be quiesced before unloading.

Parameters:

mp	Module object created via mprCreateModule

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule

MprModuleSerivce

Loadable module service.

See Also:: mprCreateModuleService, mprStartModuleService, mprStopModuleService

API Stability:: Internal.

MprPath

Path (filename) Information.

Description:: MprPath is the cross platform Path (filename) information structure.

API Stability:: Internal.

See Also:: MprDirEntry, MprFile, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

Fields:

MprTime	atime	Access time.
bool	caseMatters	Case comparisons matter.
int	checked	Path has been checked.
MprTime	ctime	Create time.
int	group	Group ID.
int64	inode	Inode number.
bool	isDir	Set if directory.
bool	isLink	Set if a symbolic link.
bool	isReg	Set if a regular file.
MprTime	mtime	Modified time.
int	owner	Owner ID.
int	perms	Permission mask.
MprOff	size	File length.
int	valid	Valid data bit.

int mprCopyPath (cchar *from, cchar *to, int omode)

Copy a file.

Description:: Create a new copy of a file with the specified open permissions mode.

Parameters:

from	Path of the existing file to copy.
to	Name of the new file copy.
omode	Posix style file open mode mask. See mprOpenFile for the various modes.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprDeletePath (cchar *path)

Delete a file.

Description:: Delete a file or directory.

Parameters:

path	String containing the path to delete.

Returns:: Returns zero if successful otherwise a negative MPR error code is returned.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetAbsPath (cchar *path)

Convert a path to an absolute path.

Description:: Get an absolute (canonical) equivalent representation of a path. On windows this path will have back-slash directory separators and will have a drive specifier. On Cygwin, the path will be a Cygwin style path with forward-slash directory specifiers and without a drive specifier. If the path is outside the cygwin filesystem (outside c:/cygwin), the path will have a /cygdrive/DRIVE prefix. To get a windows style path, use mprGetWinPath.

Parameters:

path	Path to examine.

Returns:: An absolute path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetCurrentPath ()

Return the current working directory.

Returns:: Returns an allocated string with the current working directory as an absolute path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetFirstPathSeparator (cchar *path)

Get the first path separator in a path.

Parameters:

path	Path to examine.

Returns:: Returns a reference to the first path separator in the given path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetNativePath (cchar *path)

Get a path formatted according to the native O/S conventions.

Description:: Get an equivalent absolute path formatted using the directory separators native to the O/S platform. On Windows, it will use backward slashes ("\") as the directory separator and will contain a drive specification.

Parameters:

path	Path name to examine.

Returns:: An allocated string containing the new path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathBase (cchar *path)

Get the base portion of a path.

Description:: Get the base portion of a path by stripping off all directory components.

Parameters:

path	Path name to examine.

Returns:: A path without any directory portion.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetPathBaseRef (cchar *path)

Get a reference to the base portion of a path.

Description:: Get the base portion of a path by stripping off all directory components. This returns a reference into the original path.

Parameters:

path	Path name to examine.

Returns:: A path without any directory portion. The path is a reference into the original file string.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathDir (cchar *path)

Get the directory portion of a path.

Description:: Get the directory portion of a path by stripping off the base name.

Parameters:

path	Path name to examine.

Returns:: A new string containing the directory name.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathExt (cchar *path)

Get the file extension portion of a path.

Description:: Get the file extension portion of a path. The file extension is the portion starting with the last "." in the path. It thus includes "." as the first charcter.

Parameters:

path	Path name to examine.

Returns:: A path extension.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

MprList * mprGetPathFiles (cchar *dir, int flags)

Create a list of files in a directory or subdirectories.

This call returns a list of MprDirEntry objects

Description:: Get the list of files in a directory and return a list.

Parameters:

dir	Directory to list.
flags	The flags may be set to MPR_PATH_DESCEND to traverse subdirectories. Set MPR_PATH_NODIRS to exclude directories from the results. Set to MPR_PATH_HIDDEN to include hidden files that start with ".". Set to MPR_PATH_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list.

Returns:: A list (MprList) of MprDirEntry objects.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathFirstDir (cchar *path)

Get the first directory portion of a path.

Parameters:

path	Path name to examine.

Returns:: A new string containing the directory name.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprGetPathInfo (cchar *path, MprPath *info)

Return information about a file represented by a path.

Description:: Returns file status information regarding the path.

Parameters:

path	String containing the path to query.
info	Pointer to a pre-allocated MprPath structure.

Returns:: Returns zero if successful, otherwise a negative MPR error code is returned.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathLink (cchar *path)

Get the target of a symbolic link.

Description:: Return the path pointed to by a symbolic link. Not all platforms support symbolic links.

Parameters:

path	Path name to examine.

Returns:: A path representing the target of the symbolic link.

API Stability:: Evolving.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetPathNewline (cchar *path)

Get the file newline character string for a given path.

Return the character string used to delimit new lines in text files

Parameters:

path	Use this path to specify either the root of the file system or a file on the file system.

Returns:: A string used to delimit new lines. This is typically "\n" or "\r\n".

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathParent (cchar *path)

Get the parent directory of a path.

Parameters:

path	Path name to examine.

Returns:: An allocated string containing the parent directory.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char mprGetPathSeparator (cchar *path)

Get the default path directory separator.

Return the default directory separator character used to separate directories on a given file system. Typically "/" or "\"

Parameters:

path	Use this path to specify either the root of the file system or a file on the file system.

Returns:: Character path separator.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetPathSeparators (cchar *path)

Get the path directory separator.

Return the directory separator characters used to separate directories on a given file system. Typically "/" or "\" The first entry is the default separator

Parameters:

path	Use this path to specify either the root of the file system or a file on the file system.

Returns:: The string of path separators. The first entry is the default separator.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPortablePath (cchar *path)

Get a portable path.

Description:: Get an equivalent absolute path that is somewhat portable. This means it will use forward slashes ("/") as the directory separator. This call will not remove drive specifiers.

Parameters:

path	Path name to examine.

Returns:: An allocated string containing the new path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetRelPath (cchar *dest, cchar *origin)

Get a relative path.

Description:: Get a relative path path from an origin path to a destination.

Parameters:

dest	Destination file.
origin	Starting location from which to compute a relative path to the destination If the origin is null, use the application's current working directory as the origin.

Returns:: An allocated string containing the relative directory.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetTempPath (cchar *tmpDir)

Make a temporary file.

Description:: Thread-safe way to make a unique temporary file.

Parameters:

tmpDir

Base directory in which the temp file will be allocated.

Returns:: An allocated string containing the path of the temp file.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetWinPath (cchar *path)

Convert a path to an absolute windows path.

Description:: Get a windows style, absolute (canonical) equivalent representation of a path. This path will have back-slash delimiters and a drive specifier. On non-windows systems, this returns an absolute path using mprGetAbsPath.

Parameters:

path	Path to examine.

Returns:: A windows-style absolute path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

MprList * mprGlobPathFiles (cchar *path, cchar *patterns, int flags)

Create a list of files in a directory or subdirectories that match the given wildcard patterns.

This call returns a list of filenames

Description:: Get the list of files in a directory and return a list. The patterns list may contain multiple patterns separated by a comma. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories,and a trailing "/" matches directories only. An exclusion pattern may be specified to apply to subsequent patterns by appending with "!".

Parameters:

path	Directory to list.
patterns	Wild card patterns to match.
flags	The flags may be set to MPR_PATH_DESCEND to traverse subdirectories. Set MPR_PATH_NODIRS to exclude directories from the results. Set to MPR_PATH_HIDDEN to include hidden files that start with ".". Set to MPR_PATH_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list.

Returns:: A list (MprList) of filenames.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsAbsPathContained (cchar *path, cchar *dir)

Fast version of mprIsPathContained that works only for absolute paths.

Determine if a directory is the same as or a parent of a path

Parameters:

path	Path name to examine.
dir	Directory to examine if it is a parent of path or equal to path.

Returns:: True if directory is a parent of the path or is the same as the given path.

API Stability:: Evolving.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathAbs (cchar *path)

Determine if a path is absolute.

Parameters:

path	Path name to examine.

Returns:: True if the path is absolue.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathContained (cchar *path, cchar *dir)

Determine if a directory is the same as or a parent of a path.

Parameters:

dir	Directory to examine if it is a parent of path.
path	Path name to examine.

Returns:: True if directory is a parent of the path or is the same as the given path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathDir (cchar *path)

Determine if a path is a directory.

Parameters:

path	Path name to examine.

Returns:: True if the path is a directory.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathRel (cchar *path)

Determine if a path is relative.

Parameters:

path	Path name to examine.

Returns:: True if the path is relative.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathSeparator (cchar *path, cchar c)

Test if a character is a path separarator.

Parameters:

path	Path name to identify the file system.
c	Character to test.

Returns:: Returns true if the character is a path separator on the file system containing the given path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprJoinPath (cchar *base, cchar *path)

Join paths.

Description:: Join a path to a base path. If path is absolute, it will be returned.

Parameters:

base	Directory path name to use as the base.
path	Other path name to join to the base path.

Returns:: Allocated string containing the resolved path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprJoinPathExt (cchar *path, cchar *ext)

Join an extension to a path.

Description:: Add an extension to a path if it does not already have one.

Parameters:

path	Path name to use as a base. Path is not modified.
ext	Extension to add. Must should not have a period prefix.

Returns:: Allocated string containing the resolved path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprJoinPaths (cchar *base, ...)

Join paths.

Description:: Join each given path in turn to the path. Calls mprJoinPath for each argument.

Parameters:

base	Directory path name to use as the base.
...	Other paths to join to the base path. List of other paths must be NULL terminated.

Returns:: Allocated string containing the resolved path.

API Stability:: Prototype.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprMakeDir (cchar *path, int perms, int owner, int group, bool makeMissing)

Make a directory.

Description:: Make a directory using the supplied path. Intermediate directories are created as required.

Parameters:

path	String containing the directory pathname to create.
makeMissing	If true make all required intervening directory segments.
perms	Posix style file permissions mask.
owner	User to own the directory. Set to -1 not change the owner.
group	Group to own the directory. Set to -1 not change the group.

Returns:: Returns zero if successful, otherwise a negative MPR error code is returned.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprMakeLink (cchar *path, cchar *target, bool hard)

Make a link.

Description:: Make a link at the target to the specified path. This will make symbolic or hard links depending on the value of the hard parameter.

Parameters:

path	String containing the path to link to.
target	String containing the new link path to be created.
hard	If true, make a hard link, otherwise make a soft link.

Returns:: Returns zero if successful, otherwise a negative MPR error code is returned.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

void mprMapSeparators (char *path, int separator)

Map the separators in a path.

Description:: Map the directory separators in a path to the specified separators. This is useful to change from backward to forward slashes when dealing with Windows paths.

Parameters:

path	Path name to examine.
separator	Separator character to use.

Returns:: An allocated string containing the parent directory.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprNormalizePath (cchar *path)

Normalize a path.

Description:: A path is normalized by redundant segments such as "./" and "../dir" and duplicate path separators. Path separators are mapped. Paths are not converted to absolute paths.

Parameters:

path	First path to compare.

Returns:: A newly allocated, clean path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprPathExists (cchar *path, int omode)

Determine if a file exists for a path name and can be accessed.

Description:: Test if a file can be accessed for a given mode.

Parameters:

path	Path name to test.
omode	Posix style file open mode mask. See mprOpenFile for the various modes.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprReplacePathExt (cchar *dir, cchar *ext)

Replace an extension to a path.

Description:: Remove any existing path extension and then add the given path extension.

Parameters:

dir	Directory path name to test use as the base/dir.
ext	Extension to add. The extension should not have a period prefix.

Returns:: Allocated string containing the resolved path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprResolvePath (cchar *base, cchar *path)

Resolve paths.

Description:: Resolve paths in the neighborhood of this path. Resolve operates like join, except that it joins the given paths to the directory portion of the current ("this") path. For example: Path("/usr/bin/ejs/bin").resolve("lib") will return "/usr/lib/ejs/lib". i.e. it will return the sibling directory "lib".

Resolve operates by determining a virtual current directory for this Path object. It then successively joins the given paths to the directory portion of the current result. If the next path is an absolute path, it is used unmodified. The effect is to find the given paths with a virtual current directory set to the directory containing the prior path.

Resolve is useful for creating paths in the region of the current path and gracefully handles both absolute and relative path segments.

Returns a joined (normalized) path. If path is absolute, then return path. If path is null, empty or "." then return path.

Parameters:

base	Base path to use as the base.
path	Path name to resolve against base.

Returns:: Allocated string containing the resolved path.

API Stability:: Evolving.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprSamePath (cchar *path1, cchar *path2)

Compare two paths if they are the same.

Description:: Compare two paths to see if they are equal. This normalizes the paths to absolute paths first before comparing. It does handle case sensitivity appropriately.

Parameters:

path1	First path to compare.
path2	Second path to compare.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprSamePathCount (cchar *path1, cchar *path2, ssize len)

Compare two paths if they are the same for a given length.

Description:: Compare two paths to see if they are equal. This normalizes the paths to absolute paths first before comparing. It does handle case sensitivity appropriately. The len parameter if non-zero, specifies how many characters of the paths to compare.

Parameters:

path1	First path to compare.
path2	Second path to compare.
len	How many characters to compare.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprSearchPath (cchar *path, int flags, cchar *search, ...)

Search for a path.

Description:: Search for a file using a given set of search directories.

Parameters:

path	Path name to locate. Must be an existing file or directory.
flags	Flags.
search	Variable number of directories to search.

Returns:: Allocated string containing the full path name of the located file.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprTransformPath, mprTrimPathExt

char * mprTransformPath (cchar *path, int flags)

Transform a path.

Description:: A path is transformed by cleaning and then transforming according to the flags.

Parameters:

path	First path to compare.
flags	Flags to modify the path representation.

Returns:: A newly allocated, clean path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTrimPathExt

char * mprTrimPathComponents (cchar *path, int count)

Trim path components from a path.

Description:: Trim the requested number of path components from the front or end of a path.

Parameters:

path	Path to examine.
count	Number of components to trim. If negative, trim from the end.

Returns:: An allocated string with the trimmed path.

API Stability:: Prototype.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprTrimPathDrive (cchar *path)

Trim the drive from a path.

Description:: Trim a drive specifier ("c:") from the start of a path.

Parameters:

path	Path to examine.

Returns:: An allocated string with the trimmed drive.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprTrimPathExt (cchar *path)

Trim an extension from a path.

Description:: Trim a file extension (".ext") from a path name.

Parameters:

path	Path to examine.

Returns:: An allocated string with the trimmed path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath

ssize mprWritePathContents (cchar *path, cchar *buf, ssize len, int mode)

Create a file and write contents.

Description:: The file is created, written and closed. If the file already exists, it is recreated.

Parameters:

path	Filename to create.
buf	Buffer of data to write to the file.
len	Size of the buf parameter in bytes.
mode	File permissions with which to create the file. E.g. 0644.

Returns:: The number of bytes written. Should equal len. Otherwise return a negative MPR error code.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

MprSignal

Signal control structure.

See Also:: MprSignalProc, MprSignalService, mprAddSignalHandler, mprAddStandardSignals

API Stability:: Internal.

Fields:

void *	data	Handler data.
MprDispatcher *	dispatcher	Dispatcher to service handler.
int	flags	Control flags.
MprSignalProc	handler	Signal handler (non-native).
struct MprSignal *	next	Chain of handlers on the same signo.
void(*	sigaction)()	Prior sigaction handler.
int	signo	Signal number.

MprSignal * mprAddSignalHandler (int signo, void *handler, void *arg, MprDispatcher *dispatcher, int flags)

Add a signal handler.

The signal handling mechanism will trap the specified signal if issued and create an event on the given dispatcher. This will cause the handler function to be safely run by the dispatcher. Normally, signal handlers are difficult to write as the code must be Async-safe. This API permits the use of common, single-threaded code to be used for signal handlers without worrying about pre-emption by other signals or threads

Parameters:

signo	Signal number to handle.
handler	Call back procedure to invoke. This has the signature MprSignalProc
arg	Argument to provide to the handler.
dispatcher	Event dispatcher on which to queue an event to run the handler.
flags	Set to either MPR_SIGNAL_BEFORE or MPR_SIGNAL_AFTER to run the handler before/after existing handlers.

API Stability:: Stable.

See Also:: MprSignalProc, MprSignalService, mprAddStandardSignals

void mprAddStandardSignals ()

Add standard trapping of system signals.

The trapped signals are SIGINT, SIGQUIT, SIGTERM, SIGPIPE and SIGXFSZ. SIGPIPE and SIGXFSZ are ignored. A shutdown is initiated for SIGTERM whereas SIGINT and SIGQUIT will do an abortive exit. SIGUSR1 will do an in-process restart

API Stability:: Stable.

See Also:: MprSignalProc, MprSignalService, mprAddSignalHandler

MprSocket

Socket Service.

Description:: The MPR Socket service provides IPv4 and IPv6 capabilities for both client and server endpoints. Datagrams, Broadcast and point to point services are supported. The APIs can be used in both blocking and non-blocking modes.

The socket service integrates with the MPR worker thread pool and eventing services. Socket connections can be handled by threads from the worker thread pool for scalable, multithreaded applications.

API Stability:: Stable.

See Also:: MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

API Stability:: Internal.

Fields:

char *	acceptIp	Server addresss that accepted a new connection (actual interface).
int	acceptPort	Server port doing the listening.
char *	errorMsg	Connection related error messages.
Socket	fd	Actual socket file handle.
int	flags	Current state flags.
MprWaitHandler *	handler	Wait handler.
char *	ip	Server listen address or remote client address.
struct MprSocket *	listenSock	Listening socket.
MprMutex *	mutex	Multi-thread sync.
int	port	Port to listen or connect on.
MprSocketProvider *	provider	Socket implementation provider.
MprSocketService *	service	Socket service.
struct MprSsl *	ssl	SSL configuration.
void *	sslSocket	Extended SSL socket state.

MprSocket * mprAcceptSocket (MprSocket *listen)

Accept an incoming connection.

Parameters:

listen

Listening server socket.

Returns:: A new socket connection. Windows can return NULL with error set to EAGAIN.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

MprWaitHandler * mprAddSocketHandler (MprSocket *sp, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)

Add a wait handler to a socket.

Description:: Create a wait handler that will be invoked when I/O of interest occurs on the specified socket. The wait handler is registered with the MPR event I/O mechanism.

Parameters:

sp	Socket object created via mprCreateSocket.
mask	Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
dispatcher	Dispatcher object to use for scheduling the I/O event.
proc	Callback function to invoke when an I/O event of interest has occurred.
data	Data item to pass to the callback.
flags	Socket handler flags.

Returns:: A new wait handler registered with the MPR event mechanism.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprAddSocketProvider (cchar *name, MprSocketProvider *provider)

Add a secure socket provider for SSL communications.

Parameters:

name	Name of the secure socket provider.
provider	Socket provider object.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

MprSocket * mprCloneSocket (MprSocket *sp)

Clone a socket object.

Description:: Create an exact copy of a socket object. On return both socket objects share the same O/S socket handle. If the original socket has an SSL configuration, the new socket will share the same SSL configuration object.

Returns:: A new socket object.

API Stability:: Prototype.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprCloseSocket (MprSocket *sp, bool graceful)

Close a socket.

Description:: Close a socket. If the graceful option is true, the socket will first wait for written data to drain before doing a graceful close.

Parameters:

sp	Socket object returned from mprCreateSocket
graceful	Set to true to do a graceful close. Otherwise, an abortive close will be performed.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprConnectSocket (MprSocket *sp, cchar *ip, int port, int flags)

Connect a client socket.

Description:: Open a client connection.

Parameters:

sp	Socket object returned via mprCreateSocket
ip	Host or IP address to connect to.
port	TCP/IP port number to connect to.
flags	Socket flags may use the following flags ored together: MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking. MPR_SOCKET_BROADCAST - Use IPv4 broadcast MPR_SOCKET_DATAGRAM - Use IPv4 datagrams MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket MPR_SOCKET_NODELAY - Set NODELAY on the socket MPR_SOCKET_THREAD - Process callbacks on a separate thread.

Returns:: Zero if the connection is successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

MprSocket * mprCreateSocket ()

Create a socket.

Description:: Create a new socket.

Returns:: A new socket object.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprDisconnectSocket (MprSocket *sp)

Disconnect a socket by closing its underlying file descriptor.

This is used to prevent further I/O wait events while still preserving the socket object

Parameters:

sp	Socket object.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprEnableSocketEvents (MprSocket *sp, int mask)

Enable socket events for a socket callback.

Parameters:

sp	Socket object returned from mprCreateSocket
mask	Mask of events to enable.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

ssize mprFlushSocket (MprSocket *sp)

Flush a socket.

Description:: Flush any buffered data in a socket. Standard sockets do not use buffering and this call will do nothing. SSL sockets do buffer and calling mprFlushSocket will write pending written data.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprGetSocketBlockingMode (MprSocket *sp)

Get the socket blocking mode.

Description:: Return the current blocking mode setting.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is in blocking mode. Otherwise false.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprGetSocketError (MprSocket *sp)

Get a socket error code.

Description:: This will map a Windows socket error code into a posix error code.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: A posix error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

Socket mprGetSocketHandle (MprSocket *sp)

Get the socket file descriptor.

Description:: Get the file descriptor associated with a socket.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: The Socket file descriptor used by the O/S for the socket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprGetSocketInfo (cchar *ip, int port, int *family, int *protocol, struct sockaddr **addr, Socklen *addrlen)

Get the socket for an IP:Port address.

Parameters:

ip	IP address or hostname.
port	Port number.
family	Output parameter to contain the Internet protocol family.
protocol	Output parameter to contain the Internet TCP/IP protocol.
addr	Output parameter to contain the sockaddr description of the socket address.
addrlen	Output parameter to hold the length of the sockaddr object.

Returns:: Zero if the call is successful. Otherwise return a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprGetSocketPort (MprSocket *sp)

Get the port used by a socket.

Description:: Get the TCP/IP port number used by the socket.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: The integer TCP/IP port number used by the socket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

char * mprGetSocketState (MprSocket *sp)

Get the socket state.

Description:: Get the socket state as a parseable string description.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: The an allocated string.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprHasDualNetworkStack ()

has the system got a dual IPv4 + IPv6 network stack.

Returns:: True if the network can listen on IPv4 and IPv6 on a single socket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprHasIPv6 ()

Determine if the system support IPv6.

Returns:: True if the address system supports IPv6 networking.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprHasSecureSockets ()

Determine if SSL is available.

Returns:: True if SSL is available.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprIsIPv6 (cchar *ip)

Determine if the IP address is an IPv6 address.

Parameters:

ip	IP address.

Returns:: True if the address is an IPv6 address, otherwise zero.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprIsSocketEof (MprSocket *sp)

Test if the other end of the socket has been closed.

Description:: Determine if the other end of the socket has been closed and the socket is at end-of-file.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is at end-of-file.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprIsSocketSecure (MprSocket *sp)

Determine if the socket is secure.

Description:: Determine if the socket is using SSL to provide enhanced security.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is using SSL, otherwise zero.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

Socket mprListenOnSocket (MprSocket *sp, cchar *ip, int port, int flags)

Listen on a server socket for incoming connections.

Description:: Open a server socket and listen for client connections. If ip is null, then this will listen on both IPv6 and IPv4.

Parameters:

sp	Socket object returned via mprCreateSocket
ip	IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
port	TCP/IP port number to connect to.
flags	Socket flags may use the following flags ored together: MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking. MPR_SOCKET_BROADCAST - Use IPv4 broadcast MPR_SOCKET_DATAGRAM - Use IPv4 datagrams MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket MPR_SOCKET_NODELAY - Set NODELAY on the socket MPR_SOCKET_THREAD - Process callbacks on a separate thread.

Returns:: Zero if the connection is successful. Otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprParseSocketAddress (cchar *address, char **ip, int *port, int *secure, int defaultPort)

Parse an socket address IP address.

Description:: This parses a string containing an IP:PORT specification and returns the IP address and port components. Handles ipv4 and ipv6 addresses.

Parameters:

address	An IP:PORT specification. The :PORT is optional. When an IP address contains an ipv6 port it should be written as aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii or.
ip	Pointer to receive a dynamically allocated IP string.
port	Pointer to an integer to receive the port value.
secure	Pointer to an integer to receive true if the address requires SSL.
defaultPort	The default port number to use if the address does not contain a port.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

ssize mprReadSocket (MprSocket *sp, void *buf, ssize size)

Read from a socket.

Description:: Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block untill there is some data available or the socket is disconnected.

Parameters:

sp	Socket object returned from mprCreateSocket
buf	Pointer to a buffer to hold the read data.
size	Size of the buffer.

Returns:: A count of bytes actually read. Return a negative MPR error code on errors. Return -1 for EOF and errors. On success, return the number of bytes read. Use mprIsSocketEof to distinguision between EOF and errors.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprRemoveSocketHandler (MprSocket *sp)

Remove a socket wait handler.

Description:: Removes the socket wait handler created via mprAddSocketHandler.

Parameters:

sp	Socket object created via mprCreateSocket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprSetMaxSocketAccept (int max)

Set the maximum number of accepted client connections that are permissable.

Parameters:

max	New maximum number of accepted client connections.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprSetSocketBlockingMode (MprSocket *sp, bool on)

Set the socket blocking mode.

Description:: Set the blocking mode for a socket. By default a socket is in non-blocking mode where read / write calls will not block.

Parameters:

sp	Socket object returned from mprCreateSocket
on	Set to zero to put the socket into non-blocking mode. Set to non-zero to enable blocking mode.

Returns:: The old blocking mode if successful or a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprSetSocketDispatcher (MprSocket *sp, MprDispatcher *dispatcher)

Set the dispatcher to use for socket events.

Parameters:

sp	Socket object returned from mprCreateSocket
dispatcher	Dispatcher object reference.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprSetSocketEof (MprSocket *sp, bool eof)

Set an EOF condition on the socket.

Parameters:

sp	Socket object returned from mprCreateSocket
eof	Set to true to set an EOF condition. Set to false to clear it.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprSetSocketNoDelay (MprSocket *sp, bool on)

Set the socket delay mode.

Description:: Set the socket delay behavior (nagle algorithm). By default a socket will partial packet writes a little to try to accumulate data and coalesce TCP/IP packages. Setting the delay mode to false may result in higher performance for interactive applications.

Parameters:

sp	Socket object returned from mprCreateSocket
on	Set to non-zero to put the socket into no delay mode. Set to zero to enable the nagle algorithm.

Returns:: The old delay mode if successful or a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprSocketHandshaking (MprSocket *sp)

Test if the socket is doing an SSL handshake.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the SSL stack is handshaking.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprSocketHasBufferedRead (MprSocket *sp)

Test if the socket has buffered read data.

Description:: Use this function to avoid waiting for incoming I/O if data is already buffered.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket has pending read data.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprSocketHasBufferedWrite (MprSocket *sp)

Test if the socket has buffered write data.

Description:: Use this function to detect that there is buffer data to write in a SSL stack.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket has pending write data.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

Socket mprStealSocketHandle (MprSocket *sp)

Steal the socket handle.

Description:: Return the socket handle and set the MprSocket handle to the invalid socket. This enables callers to use the O/S socket handle for their own purposes.

Parameters:

sp	Socket object returned from mprCreateSocket

API Stability:: Prototype.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprUpgradeSocket (MprSocket *sp, struct MprSsl *ssl, cchar *peerName)

Upgrade a socket to use SSL/TLS.

Parameters:

sp	Socket to upgrade.
ssl	SSL configuration to use. Set to NULL to use the default.
peerName	Required peer name in handshake with peer. Used by clients to verify the server hostname.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

ssize mprWriteSocket (MprSocket *sp, cvoid *buf, ssize len)

Write to a socket.

Description:: Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes.

Parameters:

sp	Socket object returned from mprCreateSocket
buf	Reference to a block to write to the socket.
len	Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative MPR error code on errors.

Returns:: A count of bytes actually written. Return a negative MPR error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and mprGetError() returns EAGAIN or EWOULDBLOCK.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocketString, mprWriteSocketVector

ssize mprWriteSocketString (MprSocket *sp, cchar *str)

Write to a string to a socket.

Description:: Write a string to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes.

Parameters:

sp	Socket object returned from mprCreateSocket
str	Null terminated string to write.

Returns:: A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketVector

ssize mprWriteSocketVector (MprSocket *sp, MprIOVec *iovec, int count)

Write a vector to a socket.

Description:: Do scatter/gather I/O by writing a vector of buffers to a socket.

Parameters:

sp	Socket object returned from mprCreateSocket
iovec	Vector of data to write before the file contents.
count	Count of entries in beforeVect.

Returns:: A count of bytes actually written. Return a negative MPR error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and mprGetError() returns EAGAIN or EWOULDBLOCK.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString

MprSsl

SSL control structure.

API Stability:: Internal.

Fields:

char *	caFile	Certificate verification cert file or bundle.
char *	caPath	Certificate verification cert directory (OpenSSL only).
char *	certFile	Alternatively, locate the cert in a file.
int	changed	Set if there is a change in the SSL config. Reset by providers.
char *	ciphers	Candidate ciphers to use.
void *	config	Extended provider SSL configuration.
int	configured	Set if this SSL configuration has been processed.
char *	key	Key string.
char *	keyFile	Alternatively, locate the key in a file.
MprMutex *	mutex	Multithread sync.
int	protocols	SSL protocols.
struct MprSocketProvider *	provider	Cached SSL provider to use.
char *	providerName	SSL provider to use - null if default.
int	verifyDepth	Set if the cert chain depth should be verified.
int	verifyIssuer	Set if the certificate issuer should be also verified.
int	verifyPeer	Verify the peer verificate.

void mprAddSslCiphers (struct MprSsl *ssl, cchar *ciphers)

Add the ciphers to use for SSL.

Parameters:

ssl	SSL instance returned from mprCreateSsl
ciphers	Cipher string to add to any existing ciphers.

API Stability:: Evolving.

See Also:

struct MprSsl * MprSsl* mprCloneSsl (MprSsl *src)

Create the a new SSL control structure based on an existing structure.

Parameters:

src	Structure to clone.

API Stability:: Stable.

See Also:

struct MprSsl * MprSsl* mprCreateSsl (int server)

Create the SSL control structure.

Parameters:

server

True if the SSL configuration will be used on the server side.

API Stability:: Stable.

See Also:

int mprGetSslCipherCode (cchar *cipher)

Lookup an SSL cipher by its IANA name and return the cipher IANA code.

Parameters:

cipher

Cipher IANA name.

Returns:: String cipher code. For example: given "TLS_RSA_WITH_AES_256_CBC_SHA" return 0x35.

API Stability:: Evolving.

See Also:

cchar * mprGetSslCipherName (int cipher)

Lookup an SSL cipher by its IANA code and return the string name.

Parameters:

cipher

Cipher IANA code.

Returns:: String cipher name. For example: given 0x35, return "TLS_RSA_WITH_AES_256_CBC_SHA".

API Stability:: Evolving.

See Also:

int mprLoadSsl ()

Load the SSL module.

API Stability:: Stable.

See Also:

void mprSetSslCaFile (struct MprSsl *ssl, cchar *caFile)

Set the client certificate file to use for SSL.

Parameters:

ssl	SSL instance returned from mprCreateSsl
caFile	Path to the SSL client certificate file.

API Stability:: Stable.

See Also:

void mprSetSslCaPath (struct MprSsl *ssl, cchar *caPath)

Set the path for the client certificate directory.

Description:: This is supported for OpenSSL only.

Parameters:

ssl	SSL instance returned from mprCreateSsl
caPath	Path to the SSL client certificate directory.

API Stability:: Deprecated.

See Also:

void mprSetSslCertFile (struct MprSsl *ssl, cchar *certFile)

Set certificate to use for SSL.

Parameters:

ssl	SSL instance returned from mprCreateSsl
certFile	Path to the SSL certificate file.

API Stability:: Stable.

See Also:

void mprSetSslCiphers (MprSsl *ssl, cchar *ciphers)

Set the ciphers to use.

Parameters:

ssl	SSL instance returned from mprCreateSsl
ciphers	String of suitable ciphers.

API Stability:: Evolving.

See Also:

void mprSetSslKeyFile (struct MprSsl *ssl, cchar *keyFile)

Set the key file to use for SSL.

Parameters:

ssl	SSL instance returned from mprCreateSsl
keyFile	Path to the SSL key file.

API Stability:: Stable.

See Also:

void mprSetSslProtocols (struct MprSsl *ssl, int protocols)

Set the SSL protocol to use.

Parameters:

ssl	SSL instance returned from mprCreateSsl
protocols	SSL protocols mask.

API Stability:: Evolving.

See Also:

void mprSetSslProvider (MprSsl *ssl, cchar *provider)

Set the SSL provider to use.

Parameters:

ssl	SSL instance returned from mprCreateSsl
provider	SSL provider name (openssl \| matrixssl \| est \| nanossl).

API Stability:: Stable.

See Also:

void mprVerifySslDepth (struct MprSsl *ssl, int depth)

Control the depth of SSL SSL certificate verification.

Parameters:

ssl	SSL instance returned from mprCreateSsl
depth	Set to the number of intermediate certificates to verify. Defaults to 1.

API Stability:: Evolving.

See Also:

void mprVerifySslIssuer (struct MprSsl *ssl, bool on)

Control the verification of SSL certificate issuers.

Parameters:

ssl	SSL instance returned from mprCreateSsl
on	Set to true to enable SSL certificate issuer verification.

API Stability:: Evolving.

See Also:

void mprVerifySslPeer (struct MprSsl *ssl, bool on)

Require verification of peer certificates.

Parameters:

ssl	SSL instance returned from mprCreateSsl
on	Set to true to enable peer SSL certificate verification.

API Stability:: Evolving.

See Also:

MprString

Safe String Module.

Description:: The MPR provides a suite of safe ascii string manipulation routines to help prevent buffer overflows and other potential security traps.

See Also:: fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

API Stability:: Internal.

Fields:

char * fmt (char *buf, ssize maxSize, cchar *fmt, ...)

Format a string into a static buffer.

Description:: This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.

Parameters:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The buffer.

API Stability:: Stable.

See Also:: MprString, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * fmtv (char *buf, ssize maxSize, cchar *fmt, va_list args)

Format a string into a statically allocated buffer.

Description:: This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.

Parameters:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:: The buffer;.

API Stability:: Stable.

See Also:: MprString, fmt, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * itos (int64 value)

Convert an integer to a string.

Description:: This call converts the supplied 64 bit integer to a string using base 10.

Parameters:

value

Integer value to convert.

Returns:: An allocated string with the converted number.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * itosbuf (char *buf, ssize size, int64 value, int radix)

Convert an integer to a string buffer.

Description:: This call converts the supplied 64 bit integer into a string formatted into the supplied buffer according to the specified radix.

Parameters:

buf	Pointer to the buffer that will hold the string.
size	Size of the buffer.
value	Integer value to convert.
radix	The base radix to use when encoding the number.

Returns:: Returns a reference to the string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * itosradix (int64 value, int radix)

Convert an integer to a string.

Description:: This call converts the supplied 64 bit integer to a string according to the specified radix.

Parameters:

value	Integer value to convert.
radix	The base radix to use when encoding the number.

Returns:: An allocated string with the converted number.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize mprEprintf (cchar *fmt, ...)

Print a formatted message to the standard error channel.

Description:: This is a secure replacement for fprintf(stderr).

Parameters:

fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Evolving.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize mprFprintf (struct MprFile *file, cchar *fmt, ...)

Print a formatted message to a file descriptor.

Description:: This is a replacement for fprintf as part of the safe string MPR library. It minimizes memory use and uses a file descriptor instead of a File pointer.

Parameters:

file	MprFile object returned via mprOpenFile
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize mprPrintf (cchar *fmt, ...)

Formatted print.

This is a secure verion of printf that can handle null args

Description:: This is a secure replacement for printf. It can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * mprPrintfCore (char *buf, ssize maxsize, cchar *fmt, va_list args)

Format a string into a buffer.

Description:: This routine will format the arguments into a result. If a buffer is supplied, it will be used. Otherwise if the buf argument is NULL, a buffer will be allocated. The arguments will be formatted up to the maximum size supplied by the maxsize argument. A trailing null will always be appended.

Parameters:

buf	Optional buffer to contain the formatted result.
maxsize	Maximum size of the result.
fmt	Printf style format string.
args	Variable arguments to format.

Returns:: The number of characters in the string.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * scamel (cchar *str)

Create a camel case version of the string.

Description:: Copy a string into a newly allocated block and make the first character lower case.

Parameters:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

int scaselesscmp (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is a safe replacement for strcasecmp. It can handle NULL args

Description:: Compare two strings ignoring case differences. This call operates similarly to strcmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

bool scaselessmatch (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is similar to scaselesscmp but it returns a boolean

Description:: Compare two strings ignoring case differences.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns true if the strings are equivalent, otherwise false.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * schr (cchar *str, int c)

Find a character in a string.

Description:: This is a safe replacement for strchr. It can handle NULL args.

Parameters:

str	String to examine.
c	Character to search for.

Returns:: If the character is found, the call returns a reference to the character position in the string. Otherwise, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * sclone (cchar *str)

Clone a string.

Description:: Copy a string into a newly allocated block.

Parameters:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

int scmp (cchar *s1, cchar *s2)

Compare strings.

Description:: Compare two strings. This is a safe replacement for strcmp. It can handle null args.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * scontains (cchar *str, cchar *pattern)

Find a pattern in a string.

Description:: Locate the first occurrence of pattern in a string.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize scopy (char *dest, ssize destMax, cchar *src)

Copy a string.

Description:: Safe replacement for strcpy. Copy a string and ensure the destination buffer is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is always terminated with a null.

Parameters:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.

Returns:: The number of characters in the target string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

bool sends (cchar *str, cchar *suffix)

Test if the string ends with a given pattern.

Parameters:

str	String to examine.
suffix	Pattern to search for.

Returns:: Returns TRUE if the pattern was found. Otherwise returns zero.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * sfmt (cchar *fmt, ...)

Format a string.

This is a secure verion of printf that can handle null args

Description:: Format the given arguments according to the printf style format. See mprPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * sfmtv (cchar *fmt, va_list args)

Format a string.

This is a secure verion of printf that can handle null args

Description:: Format the given arguments according to the printf style format. See mprPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

uint shash (cchar *str, ssize len)

Compute a hash code for a string.

Parameters:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:: Returns an unsigned integer hash code.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

uint shashlower (cchar *str, ssize len)

Compute a caseless hash code for a string.

Description:: This computes a hash code for the string after converting it to lower case.

Parameters:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:: Returns an unsigned integer hash code.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * sjoin (cchar *str, ...)

Catenate strings.

Description:: This catenates strings together with an optional string separator. If the separator is NULL, not separator is used. This call accepts a variable list of strings to append, terminated by a null argument.

Parameters:

str	First string to catentate.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * sjoinv (cchar *str, va_list args)

Catenate strings.

Description:: This catenates strings together with an optional string separator. If the separator is NULL, not separator is used. This call accepts a variable list of strings to append, terminated by a null argument.

Parameters:

str	First string to catentate.
args	Varargs argument obtained from va_start.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize slen (cchar *str)

Return the length of a string.

Description:: Safe replacement for strlen. This call returns the length of a string and tests if the length is less than a given maximum. It will return zero for NULL args.

Parameters:

str	String to measure.

Returns:: The length of the string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * slower (cchar *str)

Convert a string to lower case.

Description:: Convert a string to its lower case equivalent.

Parameters:

str	String to convert.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

bool smatch (cchar *s1, cchar *s2)

Compare strings.

Description:: Compare two strings. This is similar to scmp but it returns a boolean.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns true if the strings are equivalent, otherwise false.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

int sncaselesscmp (cchar *s1, cchar *s2, ssize len)

Compare strings ignoring case.

Description:: Compare two strings ignoring case differences for a given string length. This call operates similarly to strncasecmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * snclone (cchar *str, ssize len)

Clone a substring.

Description:: Copy a substring into a newly allocated block.

Parameters:

str	Pointer to the block to duplicate.
len	Number of bytes to copy. The actual length copied is the minimum of the given length and the length of the supplied string. The result is null terminated.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

int sncmp (cchar *s1, cchar *s2, ssize len)

Compare strings.

Description:: Compare two strings for a given string length. This call operates similarly to strncmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * sncontains (cchar *str, cchar *pattern, ssize limit)

Find a pattern in a string with a limit.

Description:: Locate the first occurrence of pattern in a string, but do not search more than the given character limit.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize sncopy (char *dest, ssize destMax, cchar *src, ssize len)

Copy characters from a string.

Description:: Safe replacement for strncpy. Copy bytes from a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.

Parameters:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.
len	Maximum count of characters to copy.

Returns:: Returns a reference to the destination if successful or NULL if the string won't fit.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * spbrk (cchar *str, cchar *set)

Locate the a character in a string.

Description:: This locates in the string the first occurence of any character from a given set of characters.

Parameters:

str	String to examine.
set	Set of characters to scan for.

Returns:: Returns a reference to the first character from the given set. Returns NULL if none found.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * srchr (cchar *str, int c)

Find a character in a string by searching backwards.

Description:: This locates in the string the last occurence of a character.

Parameters:

str	String to examine.
c	Character to scan for.

Returns:: Returns a reference in the string to the requested character. Returns NULL if none found.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * srejoin (char *buf, ...)

Append strings to an existing string and reallocate as required.

Description:: Append a list of strings to an existing string. The list of strings is terminated by a null argument. The call returns the size of the allocated block.

Parameters:

buf	Existing (allocated) string to reallocate. May be null. May not be a string literal.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * srejoinv (char *buf, va_list args)

Append strings to an existing string and reallocate as required.

Description:: Append a list of strings to an existing string. The list of strings is terminated by a null argument. The call returns the size of the allocated block.

Parameters:

buf	Existing (allocated) string to reallocate. May be null. May not be a string literal.
args	Varargs argument obtained from va_start.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

ssize sspn (cchar *str, cchar *set)

Find the end of a spanning prefix.

Description:: This scans the given string for characters from the set and returns an index to the first character not in the set.

Parameters:

str	String to examine.
set	Set of characters to span.

Returns:: Returns an index to the first character after the spanning set.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

bool sstarts (cchar *str, cchar *prefix)

Test if the string starts with a given pattern.

Parameters:

str	String to examine.
prefix	Pattern to search for.

Returns:: Returns TRUE if the pattern was found. Otherwise returns zero.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * ssub (cchar *str, ssize offset, ssize length)

Create a substring.

Parameters:

str	String to examine.
offset	Starting offset within str for the beginning of the substring.
length	Length of the substring in characters.

Returns:: Returns a newly allocated substring.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * stemplate (cchar *str, struct MprHash *tokens)

Replace template tokens in a string with values from a lookup table.

Tokens are ${variable} references

Parameters:

str	String to expand.
tokens	Hash table of token values to use.

Returns:: An expanded string. May return the original string if no "$" references are present.

API Stability:: Stable.

See Also:: stemplateJson

char * stemplateJson (cchar *str, struct MprJson *tokens)

Replace template tokens in a string with values from a lookup table.

Tokens are ${variable} references

Parameters:

str	String to expand.
tokens	Json object of token values to use.

Returns:: An expanded string. May return the original string if no "$" references are present.

API Stability:: Stable.

See Also:: stemplate

char * stitle (cchar *str)

Create a Title Case version of the string.

Description:: Copy a string into a newly allocated block and make the first character upper case.

Parameters:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

double stof (cchar *str)

Convert a string to a double.

Description:: This call converts the supplied string to a double.

Parameters:

str	Pointer to the string to parse.

Returns:: The double equivalent value of the string.

API Stability:: Evolving.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

int64 stoi (cchar *str)

Convert a string to an integer.

Description:: This call converts the supplied string to an integer using base 10.

Parameters:

str	Pointer to the string to parse.

Returns:: The integer equivalent value of the string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoiradix, stok, strim, supper

int64 stoiradix (cchar *str, int radix, int *err)

Convert a string to an integer.

Description:: This call converts the supplied string to an integer using the specified radix (base).

Parameters:

str	Pointer to the string to parse.
radix	Base to use when parsing the string.
err	Return error code. Set to 0 if successful.

Returns:: The integer equivalent value of the string.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stok, strim, supper

char * stok (char *str, cchar *delim, char **last)

Tokenize a string.

Description:: Split a string into tokens.

Parameters:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Last token pointer.

Returns:: Returns a pointer to the next token.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, strim, supper

struct MprList * MprList* stolist (cchar *src)

String to list.

This parses the string into space separated arguments. Single and double quotes are supported

Parameters:

src	Source string to parse.

Returns:: List of arguments.

API Stability:: Evolving.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim, supper

char * strim (cchar *str, cchar *set, int where)

Trim a string.

Description:: Trim leading and trailing characters off a string. The original string is not modified and the return value is a newly allocated string.

Parameters:

str	String to trim.
set	String of characters to remove.
where	Flags to indicate trim from the start, end or both. Use MPR_TRIM_START, MPR_TRIM_END, MPR_TRIM_BOTH.

Returns:: Returns a newly allocated trimmed string. May not equal str.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, supper

char * supper (cchar *str)

Convert a string to upper case.

Description:: Convert a string to its upper case equivalent.

Parameters:

str	String to convert.

Returns:: Returns a pointer to the converted string. Will always equal str.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stoi, stoiradix, stok, strim

MprSync

Multithreaded Synchronization Services.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

API Stability:: Internal.

Fields:

void mprAtomicAdd (volatile int *target, int value)

Atomic Add.

This is a lock free function

Parameters:

target	Address of the target word to add to.
value	Value to add to the target.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicAdd64 (volatile int64 *target, int64 value)

Atomic 64 bit Add.

This is a lock free function

Parameters:

target	Address of the target word to add to.
value	Value to add to the target.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicBarrier ()

Apply a full (read+write) memory barrier.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

int mprAtomicCas (void *volatile *target, void *expected, cvoid *value)

Atomic Compare and Swap.

This is a lock free function

Parameters:

target	Address of the target word to swap.
expected	Expected value of the target.
value	New value to store at the target.

Returns:: TRUE if the swap was successful.

API Stability:: Evolving.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicListInsert (void **head, void **link, void *item)

Atomic list insertion.

Inserts "item" at the "head" of the list. The "link" field is the next field in item. This is a lock-free function

Parameters:

head	list head.
link	Reference to the list head link field.
item	Item to insert.

API Stability:: Evolving.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicOpen ()

Open and initialize the atomic subystem.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprCond * mprCreateCond ()

Create a condition lock variable.

Description:: This call creates a condition variable object that can be used in mprWaitForCond and mprSignalCond calls.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprMutex * mprCreateLock ()

Create a Mutex lock object.

Description:: This call creates a Mutex lock object that can be used in mprLock, mprTryLock and mprUnlock calls.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprSpin * mprCreateSpinLock ()

Create a spin lock lock object.

Description:: This call creates a spinlock object that can be used in mprSpinLock, and mprSpinUnlock calls. Spin locks using MprSpin are much faster than MprMutex based locks on some systems.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprGlobalLock ()

Globally lock the application.

Description:: This call asserts the application global lock so that other threads calling mprGlobalLock will block until the current thread calls mprGlobalUnlock. WARNING: Use this API very sparingly.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprGlobalUnlock ()

Unlock the global mutex.

Description:: This call unlocks the global mutex previously locked via mprGlobalLock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprMutex * mprInitLock (MprMutex *mutex)

Initialize a statically allocated Mutex lock object.

Description:: This call initialized a Mutex lock object without allocation. The object can then be used used in mprLock, mprTryLock and mprUnlock calls.

Parameters:

mutex

Reference to an MprMutex structure to initialize.

Returns:: A reference to the supplied mutex. Returns null on errors.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprSpin * mprInitSpinLock (MprSpin *lock)

Initialize a statically allocated spinlock object.

Description:: This call initialized a spinlock lock object without allocation. The object can then be used used in mprSpinLock and mprSpinUnlock calls.

Parameters:

lock	Reference to a static MprSpin object.

Returns:: A reference to the MprSpin object. Returns null on errors.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprLock (MprMutex *lock)

Lock access.

Description:: This call asserts a lock on the given lock mutex so that other threads calling mprLock will block until the current thread calls mprUnlock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprResetCond (MprCond *cond)

Reset a condition variable.

This sets the condition variable to the unsignalled condition

Parameters:

cond	Condition variable object created via mprCreateCond

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSignalCond (MprCond *cond)

Signal a condition lock variable.

Description:: Signal a condition variable and set it to the triggered status. Existing or future caller of mprWaitForCond will be awakened. The condition variable will be automatically reset when the waiter awakes. Should only be used for single waiters. Use mprSignalMultiCond for use with multiple waiters.

This API (like nearly all MPR APIs) must only be used by MPR threads and not by non-MPR (foreign) threads. If you need to synchronize active of MPR threads with non-MPR threads, use mprCreateEventOutside which can be called from foreign threads.

Parameters:

cond	Condition variable object created via mprCreateCond

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSignalMultiCond (MprCond *cond)

Signal a condition lock variable for use with multiple waiters.

Description:: Signal a condition variable and set it to the triggered status. Existing or future callers of mprWaitForCond will be awakened. The conditional variable will not be automatically reset and must be reset manually via mprResetCond.

Parameters:

cond	Condition variable object created via mprCreateCond

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSpinLock (MprSpin *lock)

Lock a spinlock.

Description:: This call asserts a lock on the given spinlock so that other threads calling mprSpinLock will block until the curren thread calls mprSpinUnlock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSpinUnlock (MprSpin *lock)

Unlock a spinlock.

Description:: This call unlocks a spinlock previously locked via mprSpinLock or mprTrySpinLock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

bool mprTryLock (MprMutex *lock)

Attempt to lock access.

Description:: This call attempts to assert a lock on the given lock mutex so that other threads calling mprLock or mprTryLock will block until the current thread calls mprUnlock.

Returns:: Returns zero if the successful in locking the mutex. Returns a negative MPR error code if unsuccessful.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

bool mprTrySpinLock (MprSpin *lock)

Attempt to lock access on a spin lock.

Description:: This call attempts to assert a lock on the given spin lock so that other threads calling mprSpinLock or mprTrySpinLock will block until the current thread calls mprSpinUnlock.

Returns:: Returns zero if the successful in locking the spinlock. Returns a negative MPR error code if unsuccessful.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprUnlock (MprMutex *lock)

Unlock a mutex.

Description:: This call unlocks a mutex previously locked via mprLock or mprTryLock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprWaitForCond, mprWaitForMultiCond

int mprWaitForCond (MprCond *cond, MprTicks timeout)

Wait for a condition lock variable.

Description:: Wait for a condition lock variable to be signaled. If the condition is signaled before the timeout expires, this call will reset the condition variable and return. This way, it automatically resets the variable for future waiters.

Parameters:

cond	Condition variable object created via mprCreateCond
timeout	Time in milliseconds to wait for the condition variable to be signaled.

Returns:: Zero if the event was signalled. Returns < 0 for a timeout.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForMultiCond

int mprWaitForMultiCond (MprCond *cond, MprTicks timeout)

Wait for a condition lock variable for use with multiple waiters.

Description:: Wait for a condition lock variable to be signaled. Multiple waiters are supported and the condition variable must be manually reset via mprResetCond. The condition may signaled before calling mprWaitForMultiCond.

Parameters:

cond	Condition variable object created via mprCreateCond
timeout	Time in milliseconds to wait for the condition variable to be signaled.

Returns:: Zero if the event was signalled. Returns < 0 for a timeout.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond

MprTestService

Test service facility.

API Stability:: Internal.

Fields:

int	activeThreadCount	Currently active test threads.
int	argc	Count of arguments.
char **	argv	Arguments for test (not alloced).
bool	continueOnFailures	Keep testing on failures.
bool	debugOnFailures	Break to the debugger.
int	echoCmdLine	Echo the command line.
int	firstArg	Count of arguments.
MprList *	groups	Master list of test groups.
int	iterations	Times to run the test.
MprMutex *	mutex	Multi-thread sync.
cchar *	name	Name for entire test.
int	numThreads	Number of test threads.
bool	singleStep	Pause between tests.
MprTime	start	When testing began.
int	testDepth	Depth of entire test.
MprList *	testFilter	Test groups to run.
MprList *	threadData	Per thread objects.
int	totalFailedCount	Total count of failing tests.
int	totalTestCount	Total count of all tests.
int	verbose	Output activity trace.
int	workers	Count of worker threads.

bool assertTrue (MprTestGroup *gp, cchar *loc, bool success, cchar *msg)

Test assert.

Description:: This is the primary assertion test routine for unit tests. This is typically invoked by using the assert macro.

Parameters:

gp	Test group reference.
loc	Program location string including filename and line number.
success	Boolean indicating whether the test passed or failed.
msg	Message to display if the test failed.

API Stability:: Internal.

See Also:

MprTestGroup * mprAddTestGroup (MprTestService *ts, MprTestDef *def)

Add a test group to the test service.

Parameters:

ts	Test service object returned from mprCreateTestService
def	Test group definition to add.

Returns:: MprTestGroup record for the test group.

API Stability:: Internal.

See Also:

MprTestService * mprCreateTestService ()

Create the test service.

Returns:: An MprTestService control object.

API Stability:: Internal.

See Also:

int mprParseTestArgs (MprTestService *ts, int argc, char **argv, MprTestParser extraParser)

Parse test command arguments.

Parameters:

ts	Test service object returned from mprCreateTestService
argc	Count of arguments in argv.
argv	Argument array.
extraParser	Callback function to invoke to parse non-standard arguments.

Returns:: Zero if the command have been successfully parsed. Otherwise return a negative MPR error code.

API Stability:: Internal.

See Also:

void mprReportTestResults (MprTestService *ts)

Report the test results.

Description:: Test results are written to stdout.

Parameters:

ts	Test service object returned from mprCreateTestService

API Stability:: Internal.

See Also:

void mprResetTestGroup (MprTestGroup *gp)

Reset a test group.

Description:: This resets the success/fail flag for the group.

Parameters:

gp	Test group reference.

API Stability:: Internal.

See Also:

int mprRunTests (MprTestService *ts)

Run the define unit tests.

Parameters:

ts	Test service object returned from mprCreateTestService

API Stability:: Internal.

See Also:

void mprSignalTest2Complete (MprTestGroup *gp)

Signal a test is complete.

Description:: This awakens a thread that has called mprWaitForTest2ToComplete.

Parameters:

gp	Test group reference.

API Stability:: Internal.

See Also:

void mprSignalTestComplete (MprTestGroup *gp)

Signal a test is complete.

Description:: This awakens a thread that has called mprWaitForTestToComplete.

Parameters:

gp	Test group reference.

API Stability:: Internal.

See Also:

bool mprWaitForTest2ToComplete (MprTestGroup *gp, MprTicks timeout)

Wait for a test to complete.

Description:: This blocks a thread until a test has completed and is signalled by another thread calling mprSignalTest2Complete

Parameters:

gp	Test group reference.
timeout	Timeout in milliseconds to block waiting for the test to complete.

Returns:: True if the test was completed within the timeout.

API Stability:: Internal.

See Also:

bool mprWaitForTestToComplete (MprTestGroup *gp, MprTicks timeout)

Wait for a test to complete.

Description:: This blocks a thread until a test has completed and is signalled by another thread calling mprSignalTestComplete

Parameters:

gp	Test group reference.
timeout	Timeout in milliseconds to block waiting for the test to complete.

Returns:: True if the test was completed within the timeout.

API Stability:: Internal.

See Also:

MprThread

Thread Service.

Description:: The MPR provides a cross-platform thread abstraction above O/S native threads. It supports arbitrary thread creation, thread priorities, thread management and thread local storage. By using these thread primitives with the locking and synchronization primitives offered by MprMutex, MprSpin and MprCond - you can create cross platform multi-threaded applications.

See Also:: MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

API Stability:: Internal.

Fields:

MprCond *	cond	Multi-thread synchronization.
void *	data	Data argument.
MprThreadProc	entry	Users thread entry point.
int	isMain	Is the main thread.
MprMutex *	mutex	Multi-thread locking.
char *	name	Name of thead for trace.
MprOsThread	osThread	O/S thread id.
ulong	pid	Owning process id.
int	priority	Current priority.
ssize	stackSize	Only VxWorks implements.
int	stickyYield	Yielded does not auto-clear after GC.
int	waitForSweeper	Yield untill the GC sweeper is complete.
int	waiting	Waiting in mprYield.
int	yielded	Thread has yielded to GC.

MprThread * mprCreateThread (cchar *name, void *proc, void *data, ssize stackSize)

Create a new thread.

Description:: MPR threads are usually real O/S threads and can be used with the various locking services (MprMutex, MprCond, MprSpin) to enable scalable multithreaded applications.

Parameters:

name	Unique name to give the thread.
proc	Entry point function for the thread. mprStartThread will invoke this function to start the thread.
data	Thread private data stored in MprThread.data.
stackSize	Stack size to use for the thread. On VM based systems, increasing this value, does not necessarily incurr a real memory (working-set) increase. Set to zero for a default stack size.

Returns:: A MprThread object.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

MprOsThread mprGetCurrentOsThread ()

Get the O/S thread.

Description:: Get the O/S thread ID for the currently executing thread.

Returns:: Returns a platform specific O/S thread ID. On Unix, this is a pthread reference. On other systems it is a thread integer value.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

MprThread * mprGetCurrentThread ()

Get the currently executing thread.

Description:: Get the thread object for the currently executing O/S thread.

Returns:: Returns a thread object representing the current O/S thread.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

cchar * mprGetThreadName (MprThread *thread)

Get the thread name.

Description:: MPR threads are usually real O/S threads and can be used with the various locking services (MprMutex, MprCond, MprSpin) to enable scalable multithreaded applications.

Parameters:

thread

Thread object returned from mprCreateThread

Returns:: Returns a string name for the thread.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

int mprGetThreadPriority (MprThread *thread)

Get the thread priroity.

Description:: Get the current priority for the specified thread.

Parameters:

thread

Thread object returned by mprCreateThread

Returns:: An integer MPR thread priority between 0 and 100 inclusive.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

void mprSetCurrentThreadPriority (int priority)

Set the thread priroity for the current thread.

Description:: Set the current priority for the specified thread.

Parameters:

priority

Priority to associate with the thread. Mpr thread priorities are are integer values between 0 and 100 inclusive with 50 being a normal priority. The MPR maps these priorities in a linear fashion onto native O/S priorites. Useful constants are:

MPR_LOW_PRIORITY
MPR_NORMAL_PRIORITY
MPR_HIGH_PRIORITY

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetThreadPriority, mprStartThread, mprYield

void mprSetThreadPriority (MprThread *thread, int priority)

Set the thread priroity.

Description:: Set the current priority for the specified thread.

Parameters:

thread	Thread object returned by mprCreateThread
priority	Priority to associate with the thread. Mpr thread priorities are are integer values between 0 and 100 inclusive with 50 being a normal priority. The MPR maps these priorities in a linear fashion onto native O/S priorites. Useful constants are: MPR_LOW_PRIORITY MPR_NORMAL_PRIORITY MPR_HIGH_PRIORITY

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprStartThread, mprYield

int mprStartThread (MprThread *thread)

Start a thread.

Description:: Start a thread previously created via mprCreateThread. The thread will begin at the entry function defined in mprCreateThread

Parameters:

thread

Thread object returned from mprCreateThread

Returns:: Returns zero if successful, otherwise a negative MPR error code.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprYield

MprTime

Date and Time Service.

API Stability:: Stable.

See Also:: mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

Fields:

int mprCompareTime (MprTime t1, MprTime t2)

Compare two times.

Description:: Compare two times and return a code indicating which is greater, less or equal.

Parameters:

t1	First time.
t2	Second time.

Returns:: Zero if equal, -1 if t1 is less than t2 otherwise one.

API Stability:: Stable.

See Also:: MprTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

int mprCreateTimeService ()

Mpr time structure.

Description:: MprTime is the cross platform time abstraction structure. Time is stored as milliseconds since the epoch: 00:00:00 UTC Jan 1 1970. MprTime is typically a 64 bit quantity.

API Stability:: Internal.

See Also:: MprTime, mprCompareTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

void mprDecodeLocalTime (struct tm *timep, MprTime time)

Decode a time value into a tokenized local time value.

Description:: Safe replacement for localtime. This call converts the time value to local time and formats the as a struct tm.

Parameters:

timep	Pointer to a tm structure to hold the result.
time	Time to format.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

void mprDecodeUniversalTime (struct tm *timep, MprTime time)

Decode a time value into a tokenized UTC time structure.

Description:: Safe replacement for gmtime. This call converts the supplied time value to UTC time and parses the result into a tm structure.

Parameters:

timep	Pointer to a tm structure to hold the result.
time	The time to format.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprFormatLocalTime (cchar *fmt, MprTime time)

Convert a time value to local time and format as a string.

Description:: Safe replacement for ctime.

Parameters:

fmt	Time format string. See mprFormatUniversalTime for time formats.
time	Time to format. Use mprGetTime to retrieve the current time.

Returns:: The formatting time string.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprFormatTm (cchar *fmt, struct tm *timep)

Format a time value as a local time.

Description:: This call formats the time value supplied via timep.

Parameters:

fmt	The time format to use. See mprFormatUniversalTime for time formats.
timep	The time value to format.

Returns:: The formatting time string.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprFormatUniversalTime (cchar *fmt, MprTime time)

Convert a time value to universal time and format as a string.

\par \b Description: Format a time string. This uses strftime if available and so the supported formats vary from platform to platform. Strftime should supports some of these these formats described below

Parameters:

fmt

Time format string
A ... full weekday name (Monday)
a ... abbreviated weekday name (Mon)
B ... full month name (January)
b ... abbreviated month name (Jan)
C ... century. Year / 100. (0-N)
c ... standard date and time representation
D ... date (m/d/y)
d ... day-of-month (01-31)
e ... day-of-month with a leading space if only one digit ( 1-31)
F ... same as Y-m-d
H ... hour (24 hour clock) (00-23)
h ... same as b
I ... hour (12 hour clock) (01-12)
j ... day-of-year (001-366)
k ... hour (24 hour clock) (0-23)
l ... the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
M ... minute (00-59)
m ... month (01-12)
n ... a newline
P ... lower case am / pm
p ... AM / PM
R ... same as H:M
r ... same as H:M:S p
S ... second (00-59)
s ... seconds since epoch
T ... time (H:M:S)
t ... a tab.
U ... week-of-year, first day sunday (00-53)
u ... the weekday (Monday as the first day of the week) as a decimal number (1-7).
v ... is equivalent to ``e-b-Y''.
W ... week-of-year, first day monday (00-53)
w ... weekday (0-6, sunday is 0)
X ... standard time representation
x ... standard date representation
Y ... year with century
y ... year without century (00-99)
Z ... timezone name
z ... offset from UTC (-hhmm or +hhmm)
%+ ... national representation of the date and time (the format is similar to that produced by date(1)).
%% ... percent sign

Some platforms may also support the following format extensions:
E* ... POSIX locale extensions. Where "*" is one of the characters: c, C, x, X, y, Y.
G ... a year as a decimal number with century. This year is the one that contains the greater part of the week (Monday as the first day of the week).
g ... the same year as in ``G'', but as a decimal number without century (00-99).
O* ... POSIX locale extensions. Where "*" is one of the characters: d, e, H, I, m, M, S, u, U, V, w, W, y. Additionly OB implemented to represent alternative months names (used standalone, without day mentioned).
V ... the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1.

Useful formats:
RFC822: "%a, %d %b %Y %H:%M:%S %Z "Fri, 07 Jan 2003 12:12:21 PDT"
"%T %F "12:12:21 2007-01-03"
"%v "07-Jul-2003"
RFC3399: "%FT%TZ" "1985-04-12T23:20:50.52Z"

time

Time to format. Use mprGetTime to retrieve the current time.

Returns:: The formatting time string.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprGetDate (char *fmt)

Get a string representation of the current date/time.

Description:: Get the current date/time as a string according to the given format.

Parameters:

fmt	Date formatting string. See strftime for acceptable date format specifiers. If null, then this routine uses the MPR_DEFAULT_DATE format.

Returns:: An allocated date string.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTicks mprGetElapsedTicks (MprTicks mark)

Get the elapsed time since a ticks mark.

Create the ticks mark with mprGetTicks()

Parameters:

mark	Starting time stamp.

Returns:: The time elapsed since the mark was taken.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTime mprGetElapsedTime (MprTime mark)

Get the elapsed time since a starting time mark.

Parameters:

mark	Starting time created via mprGetTime()

Returns:: The time elapsed since the mark was taken.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTicks mprGetRemainingTicks (MprTicks mark, MprTicks timeout)

Return the time remaining until a timeout has elapsed.

Parameters:

mark	Starting time stamp.
timeout	Time in milliseconds.

Returns:: Time in milliseconds until the timeout elapses.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetTimeZoneOffset

MprTicks mprGetTicks ()

Get the system time.

Description:: Get the system time in milliseconds. This is a monotonically increasing time counter. It does not represent wall-clock time.

Returns:: The system time in milliseconds.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTime mprGetTime ()

Get the time.

Description:: Get the date/time in milliseconds since Jan 1 1970.

Returns:: The time in milliseconds since Jan 1 1970.

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

int mprGetTimeZoneOffset (MprTime when)

Get the current timezone offset for a given time.

Description:: Calculate the current timezone (including DST).

Parameters:

when	Time to examine to extract the timezone.

Returns:: Returns a timezone offset in msec. Local time == (UTC + offset).

API Stability:: Stable.

See Also:: MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks

MprWaitHandler

Wait Handler Service.

Description:: Wait handlers provide callbacks for when I/O events occur. They provide a wait to service many I/O file descriptors without requiring a thread per descriptor.

See Also:: MprEvent, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

API Stability:: Internal.

Fields:

MprCond *	callbackComplete	Signalled when a callback is complete.
int	desiredMask	Mask of desired events.
MprDispatcher *	dispatcher	Event dispatcher to use for I/O events.
MprEvent *	event	Event object to process I/O events.
int	fd	O/S File descriptor (sp->sock).
int	flags	Control flags.
void *	handlerData	Argument to pass to proc - managed reference.
int	notifierIndex	Index for notifier.
int	presentMask	Mask of current events.
MprEventProc	proc	Callback event procedure.
struct MprWorker *	requiredWorker	Designate the required worker thread to run the callback.
MprWaitService *	service	Wait service pointer.
struct MprThread *	thread	Thread executing the callback, set even if worker is null.

int mprCreateNotifierService (MprWaitService *ws)

Internal.

API Stability:: Internal.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

MprWaitHandler * mprCreateWaitHandler (int fd, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)

Create a wait handler.

Description:: Create a wait handler that will be invoked when I/O of interest occurs on the specified file handle The wait handler is registered with the MPR event I/O mechanism.

Parameters:

fd	File descriptor.
mask	Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
dispatcher	Dispatcher object to use for scheduling the I/O event.
proc	Callback function to invoke when an I/O event of interest has occurred.
data	Data item to pass to the callback.
flags	Wait handler flags. Use MPR_WAIT_NEW_DISPATCHER to auto-create a new dispatcher for each I/O event.

Returns:: A new wait handler registered with the MPR event mechanism.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

void mprDestroyWaitHandler (MprWaitHandler *wp)

Destroy a wait handler.

Parameters:

wp	Wait handler object.

API Stability:: Evolving.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

void mprRecallWaitHandler (MprWaitHandler *wp)

Recall a wait handler.

Description:: Signal that a wait handler should be recalled at the earliest opportunity. This is useful when a protocol stack has buffered data that must be processed regardless of whether more I/O occurs.

Parameters:

wp	Wait handler to recall.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandlerByFd, mprWaitOn

void mprRecallWaitHandlerByFd (Socket fd)

Recall a wait handler by fd.

Description:: Signal that a wait handler should be recalled at the earliest opportunity. This is useful when a protocol stack has buffered data that must be processed regardless of whether more I/O occurs.

Parameters:

fd	File descriptor that matches that of a wait handler to recall.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprWaitOn

void mprRemoveWaitHandler (MprWaitHandler *wp)

Remove a wait handler from the wait service.

Parameters:

wp	Wait handler object.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

void mprWaitForIO (MprWaitService *ws, MprTicks timeout)

Wait for I/O.

Description:

This call waits for any I/O events on wait handlers until the given timeout expires. This routine yields to the garbage collector by calling mprYield Callers must retain all required memory

Parameters:

ws	Wait service object.
timeout	Timeout in milliseconds to wait for an event.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

int mprWaitForSingleIO (int fd, int mask, MprTicks timeout)

Wait for I/O on a file descriptor.

No processing of the I/O event is done

Description:: This routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.

Parameters:

fd	File descriptor to examine.
mask	Mask of events of interest (MPR_READABLE \| MPR_WRITABLE).
timeout	Timeout in milliseconds to wait for an event.

Returns:: A count of events received.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

void mprWaitOn (MprWaitHandler *wp, int desiredMask)

Subscribe for desired wait events.

Description:: Subscribe to the desired wait events for a given wait handler.

Parameters:

wp	Wait handler created via mprCreateWaitHandler
desiredMask	Mask of desired events (MPR_READABLE \| MPR_WRITABLE).

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd

MprWorker

Worker thread structure.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

API Stability:: Internal.

Fields:

MprWorkerProc	cleanup	Procedure to cleanup after run before sleeping.
void *	data	User per-worker data.
MprCond *	idleCond	Used to wait for work.
MprTicks	lastActivity	When the worker was last used.
MprWorkerProc	proc	Procedure to run.
int	running	Worker running a job.
int	state	Worker state.
MprThread *	thread	Thread associated with this worker.
MprWorkerService *	workerService	Worker service.

int mprAvailableWorkers ()

Get the count of available worker threads Return the count of free threads in the worker thread pool.

Returns:: An integer count of worker threads.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprDedicateWorker (MprWorker *worker)

Dedicate a worker thread to a current real thread.

This implements thread affinity and is required on some platforms where some APIs (waitpid on uClibc) cannot be called on a different thread

Parameters:

worker	Worker object.
worker	Worker thread reference.

API Stability:: Internal.

See Also:: MprWorkerService, MprWorkerStats, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

ssize mprGetBusyWorkerCount ()

Get the count of workers in the busy queue.

Description:: This is thread-safe with respect to MPR->state.

Returns:: Count of workers in the busy queue.

API Stability:: Prototype.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

MprWorker * mprGetCurrentWorker ()

Get the worker object if the current thread is actually a worker thread.

Returns:: A worker thread object if the thread is a worker thread. Otherwise, NULL.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

int mprGetMaxWorkers ()

Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.

Returns:: The maximum count of worker pool threads.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprGetWorkerStats (MprWorkerStats *stats)

Get the Worker service statistics.

Parameters:

stats

Reference to stats object to receive the stats.

API Stability:: Internal.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprSetMaxWorkers (int count)

Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.

If this number if less than the current number of threads, excess threads will be gracefully pruned as they exit

Parameters:

count

Maximum limit of threads to define.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprSetMinWorkers (int count)

Set the minimum count of worker threads Set the count of threads the worker pool will have.

This will cause the worker pool to pre-create at least this many threads

Parameters:

count

Minimum count of threads to use.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetWorkerStackSize, mprStartWorker

void mprSetWorkerStackSize (int size)

Set the default worker stack size.

Parameters:

size	Stack size in bytes.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprStartWorker

MprXml

Per XML session structure.

See Also:: MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

API Stability:: Internal.

Fields:

char *	errMsg	Error message text.
MprXmlHandler	handler	Callback function.
MprBuf *	inBuf	Input data queue.
void *	inputArg	Arg for mprXmlSetInputStream()
int	lineNumber	Current line no for debug.
void *	parseArg	Arg passed to mprXmlParse()
int	quoteChar	XdbAtt quote char.
MprXmlInputStream	readFn	Read data function.
MprBuf *	tokBuf	Parsed token buffer.

cchar * mprXmlGetErrorMsg (MprXml *xp)

Get the XML error message if mprXmlParse fails.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

Returns:: A descriptive null-terminated string.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

int mprXmlGetLineNumber (MprXml *xp)

Get the source XML line number.

Description:: This call can be used from within the parser callback or when mprXmlParse fails.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

Returns:: The line number for the current token or error.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

void * mprXmlGetParseArg (MprXml *xp)

Get the XML callback argument.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

Returns:: Argument defined to use for the callback.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

MprXml * mprXmlOpen (ssize initialSize, ssize maxSize)

Open an XML parser instance.

Parameters:

initialSize	Initialize size of XML in-memory token buffer.
maxSize	Maximum size of XML in-memory token buffer. Set to -1 unlimited.

Returns:: An XML parser instance.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlParse, mprXmlSetParseArg

int mprXmlParse (MprXml *xp)

Run the XML parser.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

Returns:: Zero if successful. Otherwise returns a negative MPR error code.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlSetParseArg

void mprXmlSetInputStream (MprXml *xp, MprXmlInputStream fn, void *arg)

Define the XML parser input stream.

This

Parameters:

xp	XML parser instance returned from mprXmlOpen.
fn	Callback function to provide data to the XML parser. The callback is invoked with the signature: ssize callbac(MprXml xp, void arg, char *buf, ssize size);.
arg	Callback argument to pass to the.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

void mprXmlSetParseArg (MprXml *xp, void *parseArg)

Set the XML callback argument.

Parameters:

xp	XML parser instance returned from mprXmlOpen.
parseArg	Argument to use for the callback.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse

void mprXmlSetParserHandler (MprXml *xp, MprXmlHandler h)

Set the XML parser data handle.

Parameters:

xp	XML parser instance returned from mprXmlOpen.
h	Arbitrary data to associate with the parser.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

Functions

MprBuf * mprCloneBuf (MprBuf *orig)

Clone a buffer.

Description:: Copy the buffer and contents into a newly allocated buffer.

Parameters:

orig	Original buffer to copy.

Returns:: Returns a newly allocated buffer.

API Stability:: Stable.

char * mprCloneBufAsString (MprBuf *bp)

Clone a buffer contents.

Parameters:

bp	Buffer to copy.

Returns:: Returns a string containing the buffer contents.

API Stability:: Stable.

char * mprCloneBufMem (MprBuf *bp)

Clone a buffer contents.

Parameters:

bp	Buffer to copy.

Returns:: Returns a newly allocated memory block containing the buffer contents.

API Stability:: Stable.

int mprCreateCacheService ()

Initialize the cache service on startup.

Should only be called by the MPR init on startup

Returns:: Zero if successful.

API Stability:: Internal.

MprModuleService * mprCreateModuleService ()

Create and initialize the module service.

Returns:: MprModuleService object.

API Stability:: Internal.

bool mprGCPaused ()

Test if GC has been paused.

Returns:: True if GC has been paused via mprPauseGC

API Stability:: Prototype.

cchar * mprGetCurrentThreadName ()

Return the name of the current thread.

Returns:: A static thread name.

API Stability:: Stable.

uint64 mprGetHiResTicks ()

Get the CPU tick count.

Description:: Get the current CPU tick count. This is a system dependant high resolution timer. On some systems, this returns time in nanosecond resolution.

Returns:: The CPU time in ticks. Will return the system time if CPU ticks are not available.

API Stability:: Internal.

void mprHiddenSocketData (MprSocket *sp, ssize len, int dir)

Indicate that the application layer has buffered data for the socket.

Description:: This is used by SSL and other network stacks that buffer pending data.

Parameters:

sp	Socket object returned from mprCreateSocket
len	Length of buffered data in bytes.
dir	Buffer direction. Set to MPR_READABLE for buffered read data and MPR_WRITABLE for buffered write data.

int mprIsCmdComplete (MprCmd *cmd)

Test if a command is complete.

A command is complete when the child has exited and all command output and error output has been received

Parameters:

cmd	MprCmd object created via mprCreateCmd.

bool mprIsSocketV6 (MprSocket *sp)

Determine if the socket is using IPv6 Currently only works for server side addresses.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is using IPv6, otherwise zero.

MprJson * mprJsonQuery (MprJson *obj, cchar *keyPath, MprJson *value, int flags)

Query a JSON object for a property key path and execute the given command.

The JSON object may be a string, array or object

Parameters:

obj	JSON object to examine.
keyPath	The keyPath is a multipart property string that specifies which property or properties to examine. Examples are: user.name user['name'] users[2] users[2:4] users[-4:-1] // Range from end of array users[name == 'john'] users[age >= 50] users[phone ~ ^206] // Starts with 206 users[*] // Set a new element colors[@ != 'red'] // Array element not 'red' people..[name == 'john'] // Elipsis descends down multiple levels
value	If a value is provided, the property described by the keyPath is set to the value.
flags	If flags includes MPR_JSON_REMOVE, the property described by the keyPath is removed. If flags includes MPR_JSON_SIMPLE, the property is not parsed for expressions. Otherwise the the properties described by the keyPath are cloned and returned as a children of a container object.

Returns:: Json object containing the selected property values. The elements of the object are cloned and not references into the original object.

void mprMark (void *ptr)

Mark a memory block as in-use.

Description:: To prevent a memory block being freed by the garbage collector, it must be marked as "active". Memory blocks can define a manager that will be invoked by the garbage collector to mark any fields that are required by the original block.

Parameters:

ptr

Reference to managed memory block. This must be managed memory allocated by the MPR. Do not call mprMark on memory allocated via malloc(), strdup() or other non-MPR allocation routines. It is safe pass a NULL pointer to mprMark and this will have no effect. This is a convenient pattern where manager functions can call mprMark() without testing if the element reference is null or not.

bool mprNeedYield ()

Test if a thread should call mprYield.

Description:: This call tests if a thread should yield to the garbage collector.

API Stability:: Prototype.

int mprNotifyOn (MprWaitHandler *wp, int mask)

Begin I/O notification services on a wait handler.

Parameters:

wp	Wait handler associated with the file descriptor.
mask	Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

void mprQueueIOEvent (MprWaitHandler *wp)

Queue an IO event for dispatch on the wait handler dispatcher.

Parameters:

wp	Wait handler created via mprCreateWaitHandler

API Stability:: Stable.

void mprRelayEvent (MprDispatcher *dispatcher, void *proc, void *data, MprEvent *event)

Relay an event to a dispatcher.

This invokes the callback proc as though it was invoked from the given dispatcher

Parameters:

dispatcher	Dispatcher object created via mprCreateDispatcher
proc	Procedure to invoke.
data	Argument to proc.
event	Event object.

void mprReleaseWorker (MprWorker *worker)

Release a worker thread.

This releases a worker thread to be assignable to any real thread

Parameters:

worker	Worker object.
worker	Worker thread reference.

API Stability:: Internal.

void mprResetYield ()

Reset a sticky yield.

Description:: This call resets a sticky yield established with mprYield

API Stability:: Stable.

void mprSetLogFile (struct MprFile *file)

Set a file to be used for logging.

Parameters:

file	MprFile object instance.

API Stability:: Stable.

void mprSetLogHandler (MprLogHandler handler)

Set an MPR debug log handler.

Description:: Defines a callback handler for MPR debug and error log messages. When output is sent to the debug channel, the log handler will be invoked to accept the output message.

Parameters:

handler

Callback handler.

API Stability:: Stable.

int mprStartModuleService ()

Start the module service.

Description:: This calls the start entry point for all registered modules.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

int mprStartWorker (MprWorkerProc proc, void *data)

Start a worker thread.

Description:: Start a worker thread executing the given worker procedure callback.

Parameters:

proc	Worker procedure callback.
data	Data parameter to the callback.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

void mprStopModuleService ()

Stop the module service.

Description:: This calls the stop entry point for all registered modules.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

void mprYield (int flags)

Signify to the garbage collector that the thread is ready for garbage collection.

Description:: This routine informas the garbage collector that the thread has secured all memory that must be retained and is now ready for garbage collection. The MPR has a cooperative garbage collector that runs only when all threads are ready for collection. Consequently, it is essential that threads "yield" before sleeping or blocking.

Normally, all threads yield automatically when waiting for I/O or otherwise sleeping via standard MPR routines. MPR threads tyically yield in their event loops and thread pool idle routines, so threads should not need to call mprYield unless calling custom blocking routines or long running routines.

When calling a blocking routine, you should call mprYield(MPR_YIELD_STICK) to put the thread into a yielded state. When the blocking call returns, you should call mprResetYield()

While yielded, all transient memory must have references from "managed" objects (see mprAlloc) to ensure required memory is retained. All other memory will be reclaimed.

If a thread blocks and does not yield, it will prevent garbage collection and the applications memory size will grow unnecessarily.

Parameters:

flags

Set to MPR_YIELD_WAIT to wait until the next collection is run. Set to MPR_YIELD_COMPLETE to wait until the garbage collection is fully complete including sweep phase. This is not normally required as the sweeper runs in parallel with user threads. Set to MPR_YIELD_STICKY to remain in the yielded state. This is useful when sleeping or blocking waiting for I/O. mprResetYield must be called after setting a sticky yield.

API Stability:: Stable.

ssize print (cchar *fmt, ...)

Print to stdout and add a trailing newline.

Typedefs

typedef uint(* MprHashProc)(cvoid *name, ssize len).

Hashing function to use for the table.

Parameters:

name	Name to hash.
len	Length of the name to hash.

Returns:: An integer hash index.

typedef Offset MprOff.

Signed file offset data type.

Supports large files greater than 4GB in size on all systems

typedef Ticks MprTicks.

Elapsed time data type.

Stores time in milliseconds from some arbitrary start epoch

typedef ssize(* MprXmlInputStream)(struct MprXml *xp, void *arg, char *buf, ssize size).

XML input stream function.

Parameters:

xp	XML instance reference.
arg	to input stream.
buf	Buffer into which to read data.
size	Size of buf.

API Stability:: Stable.

typedef long size_t.

Unsigned integral type.

Equivalent in size to void*

typedef int Socket.

Argument for sockets.

typedef void(* MprTerminator)(int state, int exitStrategy, int status).

Service shutdown notifier.

Description:: Services may create shutdown notifiers, called terminators that are informed when the application commences a shutdown. The terminator may be invoked several times and the service should take appropriate action based on given the MPR state.

If the state parameter is set to MPR_STOPPING, the service should not accept any new requests, but otherwise not take any destructive actions. Note this state is required to be reversible if the shutdown is cancelled.

If the state is MPR_STOPPED, the service should cancel all running requests, close files and connections and release all resources. This state is not reversible.

This exitStrategy parameter is a flags word that defines the shutdown strategy. See mprShutdown for details.

Parameters:

state	Current MPR state. Set to MPR_STARTED, MPR_STOPPING, MPR_STOPPED and MPR_DESTROYED
exitStrategy	Flags word including the flags: MPR_EXIT_ABORT, MPR_EXIT_RESTART and MPR_EXIT_SAFE.
status	The desired application exit status.

API Stability:: Evolving.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode

typedef int(* MprBufProc)(struct MprBuf *bp, void *arg).

Buffer refill callback function.

Description:: Function to call when the buffer is depleted and needs more data.

Parameters:

buf	Instance of an MprBuf.
arg	Data argument supplied to mprSetBufRefillProc

Returns:: The callback should return 0 if successful, otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

typedef void(* MprCacheProc)(struct MprCache *cache, cchar *key, cchar *data, int event).

Cache item expiry callback.

Parameters:

cache	Cache object.
key	Cached item key.
data	Cached item data.
event	Event of interest.

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

typedef void(* MprForkCallback)(void *arg).

Callback function before doing a fork().

API Stability:: Stable.

See Also:: mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

typedef void(* MprEventProc)(void *data, struct MprEvent *event).

Event callback function.

Returns:: Return non-zero if the dispatcher is deleted. Otherwise return 0.

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

typedef int(* MprListCompareProc)(cvoid *arg1, cvoid *arg2).

List comparison procedure for sorting.

Description:: Callback function signature used by mprSortList

Parameters:

arg1	First list item to compare.
arg2	Second list item to compare.

Returns:: Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.

API Stability:: Stable.

See Also:: MprList, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

typedef int(* MprSortProc)(cvoid *p1, cvoid *p2, void *ctx).

Quicksort callback function.

Description:: This is a quicksort callback with a context argument.

Parameters:

p1	Pointer to first element.
p2	Pointer to second element.
ctx	Context argument to provide to comparison function.

Returns:: -1, 0, or 1, depending on if the elements are p1 < p2, p1 == p2 or p1 > p2.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

typedef void(* MprLogHandler)(int flags, int level, cchar *msg).

Log handler callback type.

Description:: Callback prototype for the log handler. Used by mprSetLogHandler to define a message logging handler to process log and error messages.

Parameters:

file	Source filename. Derived by using FILE
line	Source line number. Derived by using LINE
flags	Error flags.
level	Message logging level. Levels are 0-9 with zero being the most verbose.
msg	Message being logged.

API Stability:: Stable.

See Also:: mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

typedef void(* MprManager)(void *ptr, int flags).

Mpr memory block manager prototype.

Parameters:

ptr	Any memory context allocated by the MPR.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

typedef void(* MprMemNotifier)(int cause, int policy, size_t size, size_t total).

Memory allocation error callback.

Notifiers are called if a low memory condition exists

Parameters:

cause	Set to the cause of the memory error. Set to MPR_MEM_WARNING if the allocation will exceed the warnHeap limit. Set to MPR_MEM_LIMIT if it would exceed the maxHeap memory limit. Set to MPR_MEM_FAIL if the allocation failed. Set to MPR_MEM_TOO_BIG if the allocation block size is too large. Allocations will be rejected for MPR_MEM_FAIL and MPR_MEM_TOO_BIG, otherwise the allocations will proceed and the memory notifier will be invoked.
policy	Memory depletion policy. Set to one of MPR_ALLOC_POLICY_NOTHING, MPR_ALLOC_POLICY_PRUNE, MPR_ALLOC_POLICY_RESTART or MPR_ALLOC_POLICY_EXIT
size	Size of the allocation that triggered the low memory condition.
total	Total memory currently in use.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

typedef int(* MprModuleEntry)(void *data, MprModule *mp).

Loadable module entry point signature.

Description:: Loadable modules can have an entry point that is invoked automatically when a module is loaded.

Parameters:

data	Data passed to mprCreateModule.
mp	Module object reference returned from mprCreateModule

Returns:: A new MprModule structure for the module. Return NULL if the module can't be initialized.

API Stability:: Stable.

See Also:: MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

typedef int(* MprModuleProc)(struct MprModule *mp).

Module start/stop point function signature.

Parameters:

mp	Module object reference returned from mprCreateModule

Returns:: Zero if successful, otherwise return a negative MPR error code.

API Stability:: Stable.

See Also:: MprModule, MprModuleEntry, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

typedef void(* MprSignalProc)(void *arg, struct MprSignal *sp).

Signal callback procedure.

API Stability:: Stable.

See Also:: MprSignalService, mprAddSignalHandler, mprAddStandardSignals

typedef int(* MprSocketPrebind)(struct MprSocket *sock).

typedef int(* MprSocketProc)(void *data, int mask).

Socket I/O callback procedure.

Proc returns non-zero if the socket has been deleted

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

typedef int(* MprTestParser)(int argc, char **argv).

Callback parser for non-standard command line arguments.

API Stability:: Internal.

See Also:

typedef void(* MprTestProc)(struct MprTestGroup *tp).

Unit test callback procedure.

API Stability:: Internal.

See Also:

typedef void(* MprThreadProc)(void *arg, struct MprThread *tp).

Thread main procedure.

Parameters:

arg	Argument to the thread main.
tp	Thread instance reference.

API Stability:: Stable.

See Also:: MprThread, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprNeedYield, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

typedef void(* MprWorkerProc)(void *data, struct MprWorker *worker).

Worker thread callback signature.

Parameters:

data	worker callback data. Set via mprStartWorker or mprActivateWorker.
worker	Reference to the worker thread object.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

typedef int(* MprXmlHandler)(struct MprXml *xp, int state, cchar *tagName, cchar *attName, cchar *value).

XML callback handler.

Parameters:

xp	XML instance reference.
state	XML state.
tagName	Current XML tag.
attName	Current XML attribute.
value	Current XML element value.

API Stability:: Stable.

See Also:: MprXml, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

MprCmdChild

Child status structure.

API Stability:: Internal.

Fields:

MprCmdService

Command execution service.

API Stability:: Internal.

Fields:

MprCond

Condition variable for single and multi-thread synchronization.

API Stability:: Internal.

Fields:

pthread_cond_t	cv	Unix pthreads condition variable.
struct MprMutex *	mutex	Thread synchronization mutex.
int	triggered	Value of the condition.

MprDirEntry

Directory entry description.

Description:: The MprGetDirList will create a list of directory entries.

Fields:

bool	isDir	True if the file is a directory.
bool	isLink	True if the file is a symbolic link.
MprTime	lastModified	Time the file was last modified.
char *	name	Name of the file.
MprOff	size	Size of the file.

API Stability:: Internal.

MprFreeMem

Block structure when on a free list.

API Stability:: Internal.

Fields:

struct MprFreeMem *		next	Next free block.
struct MprFreeMem *		prev	Previous free block.

MprFreeQueue

Free queue head structure.

Fields:

MprMem	blk	Unused in queue head.
uint	count	Number of blocks on the queue.
MprSpin	lock	Queue lock-free lock.
MprMemSize	minSize	Minimum size of blocks in queue. This is the user block size sans MprMem header.
struct MprFreeMem *	next	Next free block.
struct MprFreeMem *	prev	Previous free block.

MprHash

Hash table control structure.

See Also:

Fields:

MprKey **	buckets	Hash collision bucket table.
int	flags	Hash control flags.
MprHashProc	fn	Hash function.
int	length	Number of symbols in the table.
MprMutex *	mutex	GC marker sync.
int	size	Size of the buckets array.

API Stability:: Internal.

MprHeap

Memory allocator heap.

API Stability:: Internal.

Fields:

int	allocPolicy	Memory allocation depletion policy.
int	collecting	Manual GC is running.
int	compact	Next GC sweep should do a full compact.
int	flags	GC operational control flags.
int	freedBlocks	True if the last sweep freed blocks.
MprFreeQueue	freeq[MPR_ALLOC_NUM_QUEUES]	Heap free queues.
int	from	Eligible mprCollectGarbage flags.
MprCond *	gcCond	GC sleep cond var.
int	gcEnabled	GC is enabled.
int	gcRequested	GC has been requested.
int	hasError	Memory allocation error.
int	iteration	GC iteration counter (debug only).
int	mark	Mark version.
int	marking	Actually marking objects now.
int	mustYield	Threads must yield for GC which is due.
int	nextSeqno	Next sequence number.
MprMemNotifier	notifier	Memory allocation failure callback.
int	pageSize	System page size.
int	printStats	Print diagnostic heap statistics.
uint64	priorFree	Last sweep free memory.
int	priorWeightedCount	Prior weighted count after last sweep.
MprRegion *	regions	List of memory regions.
int	regionSize	Memory allocation region size.
struct MprList *	roots	List of GC root objects.
int	scribble	Scribble over freed memory (slow).
MprMemStats	stats	Memory allocation statistics.
struct MprThread *	sweeper	GC sweeper thread.
int	sweeping	Actually sweeping objects now.
int	track	Track memory allocations (requires BIT_MPR_ALLOC_DEBUG).
int	verify	Verify memory contents (very slow).
int	workDone	Count of allocations weighted by block size.
int	workQuota	Quota of work done before idle GC worthwhile.

MprIOVec

Vectored write array.

API Stability:: Internal.

Fields:

ssize		len	Length of block to write.
char *		start	Start of block to write.

MprJsonCallback

JSON parsing callbacks.

API Stability:: Internal.

Fields:

int(*	checkBlock)(struct MprJsonParser parser, cchar name, bool leave)	Check state callback for JSON deserialization. This function is called at the entry and exit of object levels for arrays and objects.
MprJson (	createObj)(struct MprJsonParser *parser, int type)	MakeObject callback for JSON deserialization. This function is called to construct an object for each level in the object tree. Objects will be either arrays or objects.
bool(*	match)(struct MprJsonParser parser, cchar str, cchar *pattern)	Pattern matching callback.
void(*	parseError)(struct MprJsonParser parser, cchar msg)	Handle a parse error. This function is called from mprSetJsonError to handle error reporting.
int(*	setValue)(struct MprJsonParser parser, MprJson obj, cchar name, MprJson child)	Set a property value in an object.

MprJsonParser

JSON parser.

API Stability:: Internal.

Fields:

MprKeyValue

Key value pairs for use with MprList or MprKey.

API Stability:: Stable.

Fields:

int	flags	General flags word.
void *	key	Key string.
void *	value	Associated value for the key.

MprMemStats

Memory allocator statistics.

API Stability:: Internal.

Fields:

uint64	bytesAllocated	Bytes currently allocated. Includes active and free.
uint64	bytesFree	Bytes currently free and retained in the heap queues.
uint64	cacheHeap	Heap cache. Try to keep at least this amount in the free queues.
uint64	errors	Allocation errors.
int	inMemException	Recursive protect.
uint64	lowHeap	Low memory level at which to initiate a collection.
uint64	maxHeap	Max memory that can be allocated.
uint	numCpu	Number of CPUs.
uint	pageSize	System page size.
uint64	ram	System RAM size in bytes.
uint64	rss	OS calculated resident stack size in bytes.
uint64	user	System user RAM size in bytes (excludes kernel).
uint64	warnHeap	Warn if heap size exceeds this level.

MprMutex

Multithreading lock control structure.

Description:: MprMutex is used for multithread locking in multithreaded applications.

Fields:

API Stability:: Internal.

MprRegion

Memmory regions allocated from the O/S.

API Stability:: Internal.

Fields:

MprMem *	end	End of region data.
int	freeable	Set to true when completely unused.
struct MprRegion *	next	Next region.
size_t	size	Size of region including region header.
MprMem *	start	Start of region data.

MprRomInode

A RomInode is created for each file in the Rom file system.

API Stability:: Internal.

Fields:

uchar *	data	Pointer to file data.
int	num	Inode number.
char *	path	File path.
int	size	Size of file.

MprSignalInfo

Per signal structure.

API Stability:: Internal.

Fields:

int

triggered

Set to true when triggered.

MprSignalService

Signal service control.

API Stability:: Internal.

Fields:

int	hasSignals	Signal sent to process.
MprSignalInfo	info[MPR_MAX_SIGNALS]	Actual signal info and arg.
MprMutex *	mutex	Multithread sync.
struct sigaction	prior[MPR_MAX_SIGNALS]	Prior sigaction handler before hooking.
MprSignal **	signals	Signal handlers.
MprList *	standard	Standard signal handlers.

MprSocketProvider

Socket service provider interface.

API Stability:: Internal.

Fields:

void(*	closeSocket)(struct MprSocket *socket, bool graceful)	Close a socket. Description:Close a socket. If the graceful option is true, the socket will first wait for written data to drain before doing a graceful close. socketSocket object returned from mprCreateSocketgracefulSet to true to do a graceful close. Otherwise, an abortive close will be performed. API Stability:Stable
void *	data	Socket provider private data.
void(*	disconnectSocket)(struct MprSocket *socket)	Disconnect a socket by closing its underlying file descriptor. This is used to prevent further I/O wait events while still preserving the socket object. socketSocket object API Stability:Stable
ssize(*	flushSocket)(struct MprSocket *socket)	Flush a socket. Description:Flush any buffered data in a socket. Standard sockets do not use buffering and this call will do nothing. SSL sockets do buffer and calling mprFlushSocket will write pending written data. socketSocket object returned from mprCreateSocketA count of bytes actually written. Return a negative MPR error code on errors. API Stability:Stable
char *	name	Socket provider name.
ssize(*	readSocket)(struct MprSocket socket, void buf, ssize size)	Read from a socket. Description:Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block untill there is some data available or the socket is disconnected. socketSocket object returned from mprCreateSocketbufPointer to a buffer to hold the read data. sizeSize of the buffer. A count of bytes actually read. Return a negative MPR error code on errors. Return -1 for EOF and errors. On success, return the number of bytes read. Use mprIsSocketEof to distinguision between EOF and errors. API Stability:Stable
char (	socketState)(struct MprSocket *socket)	Get the socket state. Description:Get the socket state as a parseable string description spSocket object returned from mprCreateSocketThe an allocated string API Stability:Stable
int(*	upgradeSocket)(struct MprSocket socket, struct MprSsl ssl, cchar *peerName)	Upgrade a socket to use SSL/TLS. spSocket to upgrade sslSSL configuration to use. Set to NULL to use the default. peerNameRequired peer name in handshake with peer. Used by clients to verify the server hostname. Zero if successful, otherwise a negative MPR error code. API Stability:Stable
ssize(*	writeSocket)(struct MprSocket socket, cvoid buf, ssize size)	Write to a socket. Description:Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. socketSocket object returned from mprCreateSocketbufReference to a block to write to the socket sizeLength of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative MPR error code on errors. A count of bytes actually written. Return a negative MPR error code on errors. API Stability:Stable

MprSocketService

Mpr socket service class.

API Stability:: Internal.

Fields:

int	hasIPv6	System has supoprt for IPv6.
int	maxAccept	Maximum number of accepted client socket connections.
MprMutex *	mutex	Multithread locking.
int	numAccept	Count of client socket connections.
MprSocketPrebind	prebind	Prebind callback.
MprHash *	providers	Secure socket providers.
MprList *	secureSockets	List of secured (matrixssl) sockets.
char *	sslProvider	Default secure provider for SSL connections.
MprSocketProvider *	standardProvider	Socket provider for non-SSL connections.

MprSpin

Multithreading spin lock control structure.

Description:: MprSpin is used for multithread locking in multithreaded applications.

Fields:

API Stability:: Internal.

MprTestCase

Test case structure.

API Stability:: Internal.

Fields:

MprTestDef

Test case definition.

API Stability:: Internal.

Fields:

MprTestFailure

Test failure record.

API Stability:: Internal.

Fields:

char *		loc	Program location of the failure.
char *		message	Failure message typically the assertion program text.

MprTestGroup

A test group is a group of tests to cover a unit of functionality.

API Stability:: Internal.

Fields:

MprList *	cases	List of tests in this group.
struct HttpConn *	conn	Http connection for this group.
char *	content	Cached response content.
void *	data	Test specific data.
MprTestDef *	def	Test definition ref.
MprDispatcher *	dispatcher	Per group thread dispatcher.
int	failedCount	Total failures of this test.
MprList *	failures	List of all failures.
char *	fullName	Fully qualified name of test.
MprList *	groups	List of groups.
int	hasInternet	Convenience flag for internet available for use.
int	hasIPv6	Convenience flag for IPv6 service.
struct Http *	http	Http service.
MprMutex *	mutex	Multi-thread sync.
char *	name	Name of test.
struct MprTestGroup *	parent	Parent test group.
struct MprTestGroup *	root	Top level test group parent.
MprTestService *	service	Reference to the service.
bool	skip	Skip this test.
bool	skipWarned	Warned that test will be skipped.
bool	success	Result of last run.
int	testComplete	Test complete signal.
int	testCount	Count of tests.
int	testDepth	Depth at which test should run.

MprThreadLocal

Thread local data storage.

API Stability:: Internal.

Fields:

pthread_key_t

key

Data key.

MprThreadService

Thread service.

API Stability:: Internal.

Fields:

struct MprThread *	eventsThread	Event service thread.
struct MprThread *	mainThread	Main application thread.
MprCond *	pauseThreads	Waiting for threads to yield.
ssize	stackSize	Default thread stack size.
MprList *	threads	List of all threads.

MprWaitService

Wait Service.

API Stability:: Internal.

Fields:

MprWorkerService

Worker Thread Service.

Description:: The MPR provides a worker thread pool for rapid starting and assignment of threads to tasks.

Fields:

MprList *	busyThreads	List of threads to service tasks.
MprList *	idleThreads	List of threads to service tasks.
int	maxThreads	Max # threads in worker pool.
int	maxUsedThreads	Max threads ever used.
int	minThreads	Max # threads in worker pool.
MprMutex *	mutex	Per task synchronization.
int	nextThreadNum	Unique next thread number.
int	numThreads	Current number of threads in worker pool.
struct MprEvent *	pruneTimer	Timer for excess threads pruner.
ssize	stackSize	Stack size for worker threads.
MprWorkerProc	startWorker	Worker thread startup hook.

API Stability:: Internal.

MprBufProc	Buffer refill callback function.
MprCacheProc	Cache item expiry callback.
MprCmdChild	Child status structure.
MprCmdService	Command execution service.
MprCond	Condition variable for single and multi-thread synchronization.
MprDirEntry	Directory entry description.
MprEventProc	Event callback function.
MprForkCallback	Callback function before doing a fork().
MprFreeMem	Block structure when on a free list.
MprFreeQueue	Free queue head structure.
MprHash	Hash table control structure.
MprHashProc	Hashing function to use for the table.
MprHeap	Memory allocator heap.
MprIOVec	Vectored write array.
MprJsonCallback	JSON parsing callbacks.
MprJsonParser	JSON parser.
MprKeyValue	Key value pairs for use with MprList or MprKey.
MprListCompareProc	List comparison procedure for sorting.
MprLogHandler	Log handler callback type.
MprManager	Mpr memory block manager prototype.
MprMemNotifier	Memory allocation error callback.
MprMemStats	Memory allocator statistics.
MprModuleEntry	Loadable module entry point signature.
MprModuleProc	Module start/stop point function signature.
MprMutex	Multithreading lock control structure.
MprOff	Signed file offset data type.
MprRegion	Memmory regions allocated from the O/S.
MprRomInode	A RomInode is created for each file in the Rom file system.
MprSignalInfo	Per signal structure.
MprSignalProc	Signal callback procedure.
MprSignalService	Signal service control.
MprSocketPrebind	Callback before binding a socket.
MprSocketProc	Socket I/O callback procedure.
MprSocketProvider	Socket service provider interface.
MprSocketService	Mpr socket service class.
MprSortProc	Quicksort callback function.
MprSpin	Multithreading spin lock control structure.
MprTerminator	Service shutdown notifier.
MprTestCase	Test case structure.
MprTestDef	Test case definition.
MprTestFailure	Test failure record.
MprTestGroup	A test group is a group of tests to cover a unit of functionality.
MprTestParser	Callback parser for non-standard command line arguments.
MprTestProc	Unit test callback procedure.
MprThreadLocal	Thread local data storage.
MprThreadProc	Thread main procedure.
MprThreadService	Thread service.
MprTicks	Elapsed time data type.
MprWaitService	Wait Service.
MprWorkerProc	Worker thread callback signature.
MprWorkerService	Worker Thread Service.
MprWorkerStats	Statistics for Workers.
MprXmlHandler	XML callback handler.
MprXmlInputStream	XML input stream function.
Socket	Argument for sockets.
size_t	Unsigned integral type.

#define	BIT_MAX_EVENTS 32
	Maximum number of notifier events.
#define	BIT_MPR_LOGGING 1
	Default for logging is "on".
#define	BIT_MPR_MAX_PASSWORD 256
	Max password length.
#define	MPR_ALLOC_MANAGER 0x1
	Reserve room for a manager.
#define	MPR_ALLOC_PAD_MASK 0x1
	Flags that impact padding.
#define	MPR_ALLOC_POLICY_EXIT 3
	Exit the app if maxHeap exceeded.
#define	MPR_ALLOC_POLICY_NOTHING 0
	Do nothing.
#define	MPR_ALLOC_POLICY_PRUNE 1
	Prune all non-essential memory and continue.
#define	MPR_ALLOC_POLICY_RESTART 2
	Gracefully restart the app if memory maxHeap level is exceeded.
#define	MPR_ALLOC_ZERO 0x2
	Zero memory.
#define	MPR_ARGV_ARGS_ONLY 0x1
	Command is missing program name.
#define	MPR_ASSERT_MSG 0x10
	Originated from assert.
#define	MPR_BACKGROUND_PRIORITY 15
	May only get CPU if idle.
#define	MPR_CACHE_ADD 0x2
	mprWriteCache option to add key only if not already existing.
#define	MPR_CACHE_APPEND 0x8
	mprWriteCache option to set and append if already existing.
#define	MPR_CACHE_NOTIFY_CREATE 1
	Item has been created.
#define	MPR_CACHE_NOTIFY_REMOVE 2
	Item is about to be removed.
#define	MPR_CACHE_NOTIFY_UPDATE 4
	Item has been updated.
#define	MPR_CACHE_PREPEND 0x10
	mprWriteCache option to set and prepend if already existing.
#define	MPR_CACHE_SET 0x4
	mprWriteCache option to update key value, create if required.
#define	MPR_CACHE_SHARED 0x1
	Use shared cache for mprCreateCache()
#define	MPR_CG_DEFAULT 0x0
	mprGC flag to run GC if necessary.
#define	MPR_CMD_DETACH 0x4
	mprRunCmd flag to detach the child process and don't wait.
#define	MPR_CMD_ERR 0x4000
	mprRunCmd flag to capture stdout.
#define	MPR_CMD_EXACT_ENV 0x8
	mprRunCmd flag to use the exact environment (no inherit from parent).
#define	MPR_CMD_IN 0x1000
	mprRunCmd flag to connect to stdin.
#define	MPR_CMD_NEW_SESSION 0x1
	mprRunCmd flag to create a new session on unix.
#define	MPR_CMD_OUT 0x2000
	mprRunCmd flag to capture stdout.
#define	MPR_CMD_SHOW 0x2
	mprRunCmd flag to show the window of the created process on windows.
#define	MPR_CMD_STDERR 2
	Stderr for the client side.
#define	MPR_CMD_STDIN 0
	Stdout for the client side.
#define	MPR_CMD_STDOUT 1
	Stdin for the client side.
#define	MPR_CMD_VXWORKS_EOF "_ _EOF_ _"
	Special string for VxWorks CGI to emit to signal EOF.
#define	MPR_CMD_VXWORKS_EOF_LEN 9
	Length of MPR_CMD_VXWORKS_EOF.
#define	MPR_CREATED 1
	Applicationa and MPR services started.
#define	MPR_CRITICAL_PRIORITY 99
	May not yield.
#define	MPR_DAEMON 0x10
	Make the process a daemon.
#define	MPR_DEBUG 4
	Debug information trace level.
#define	MPR_DECODE_TOKEQ 1
	Decode base 64 blocks up to a NULL or equals.
#define	MPR_DEFAULT_DATE "%a %b %d %T %Y %Z"
	Default date format used in mprFormatLocalTime/mprFormatUniversalTime when no format supplied.
#define	MPR_DEFAULT_MAX_THREADS 5
	Default max threads.
#define	MPR_DEFAULT_MIN_THREADS 0
	Default min threads.
#define	MPR_DELAY_GC_THREAD 0x8
	Delay starting the GC thread.
#define	MPR_DESTROYED 6
	Application and MPR object destroyed.
#define	MPR_DESTROYING 5
	Destroying core MPR services and releasing memory.
#define	MPR_DIAG 3
	Diagnostic trace level.
#define	MPR_DISABLE_GC 0x1
	Disable GC.
#define	MPR_DISPATCHER_AUTO 0x8
	Dispatcher was auto created in response to accept event.
#define	MPR_DISPATCHER_DESTROYED 0x4
	Dispatcher has been destroyed.
#define	MPR_DISPATCHER_IMMEDIATE 0x1
	Dispatcher should run using the service events thread.
#define	MPR_DISPATCHER_WAITING 0x2
	Dispatcher waiting for an event in mprWaitForEvent.
#define	MPR_ERR -1
	Default error code.
#define	MPR_ERR_ABORTED -2
	Action aborted.
#define	MPR_ERR_ALREADY_EXISTS -3
	Item already exists.
#define	MPR_ERR_BAD_ARGS -4
	Bad arguments or paramaeters.
#define	MPR_ERR_BAD_FORMAT -5
	Bad input format.
#define	MPR_ERR_BAD_HANDLE -6
	Bad file handle.
#define	MPR_ERR_BAD_STATE -7
	Module is in a bad state.
#define	MPR_ERR_BAD_SYNTAX -8
	Input has bad syntax.
#define	MPR_ERR_BAD_TYPE -9
	Bad object type.
#define	MPR_ERR_BAD_VALUE -10
	Bad or unexpected value.
#define	MPR_ERR_BASE -1
	Base error code.
#define	MPR_ERR_BUSY -11
	Resource is busy.
#define	MPR_ERR_CANT_ACCESS -12
	Cannot access the file or resource.
#define	MPR_ERR_CANT_ALLOCATE -13
	Cannot allocate resource.
#define	MPR_ERR_CANT_COMPLETE -14
	Operation can't complete.
#define	MPR_ERR_CANT_CONNECT -15
	Cannot connect to network or resource.
#define	MPR_ERR_CANT_CREATE -16
	Cannot create the file or resource.
#define	MPR_ERR_CANT_DELETE -17
	Cannot delete the resource.
#define	MPR_ERR_CANT_FIND -18
	Cannot find resource.
#define	MPR_ERR_CANT_INITIALIZE -19
	Cannot initialize resource.
#define	MPR_ERR_CANT_LOAD -20
	Cannot load the resource.
#define	MPR_ERR_CANT_OPEN -21
	Cannot open the file or resource.
#define	MPR_ERR_CANT_READ -22
	Cannot read from the file or resource.
#define	MPR_ERR_CANT_WRITE -23
	Cannot write to the file or resource.
#define	MPR_ERR_DELETED -24
	Resource has been deleted.
#define	MPR_ERR_MEMORY -25
	Memory allocation error.
#define	MPR_ERR_NETWORK -26
	Underlying network error.
#define	MPR_ERR_NOT_INITIALIZED -27
	Module or resource is not initialized.
#define	MPR_ERR_NOT_READY -28
	Resource is not ready.
#define	MPR_ERR_OK 0
	Success.
#define	MPR_ERR_READ_ONLY -29
	The operation timed out.
#define	MPR_ERR_TIMEOUT -30
	Operation exceeded specified time allowed.
#define	MPR_ERR_TOO_MANY -31
	Too many requests or resources.
#define	MPR_ERR_WONT_FIT -32
	Requested operation won't fit in available space.
#define	MPR_ERR_WOULD_BLOCK -33
	Blocking operation would block.
#define	MPR_ERROR 0
	Standard logging trace levels are 0 to 9 with 0 being the most verbose.
#define	MPR_ERROR_MSG 0x20
	Originated from mprError.
#define	MPR_EVENT_ASYNC 1
	Windows async select.
#define	MPR_EVENT_BLOCK 0x20
	Blocking flag for mprCreateEventOutside.
#define	MPR_EVENT_CONTINUOUS 0x1
	Timer event runs is automatically rescheduled.
#define	MPR_EVENT_DONT_QUEUE 0x4
	Don't queue the event.
#define	MPR_EVENT_EPOLL 2
	epoll_wait.
#define	MPR_EVENT_KQUEUE 3
	BSD kqueue.
#define	MPR_EVENT_PRIORITY 50
	Normal priority.
#define	MPR_EVENT_QUICK 0x2
	Execute inline without executing via a thread.
#define	MPR_EVENT_RUNNING 0x10
	Event currently executing.
#define	MPR_EVENT_SELECT 4
	traditional select().
#define	MPR_EVENT_STATIC_DATA 0x8
	Event data is permanent and should not be marked by GC.
#define	MPR_EVENT_TIME_SLICE 20 /* 20 msec */
	Events.
#define	MPR_EXIT_ABORT 0x1
	Abort everything and call exit().
#define	MPR_EXIT_NORMAL 0x0
	Normal (graceful) exit.
#define	MPR_EXIT_RESTART 0x4
	Restart after exiting.
#define	MPR_EXIT_SAFE 0x2
	Graceful shutdown only if all requests complete.
#define	MPR_EXIT_TIMEOUT -1
	Use timeout specified via mprSetExitTimeout
#define	MPR_FATAL_MSG 0x800
	Fatal error, log and exit.
#define	MPR_GC_COMPLETE 0x4
	mprGC flag to force start a GC and wait until the GC cycle fully completes including sweep phase.
#define	MPR_GC_FORCE 0x1
	mprGC flag to force start a GC sweep whether it is required or not.
#define	MPR_GC_NO_BLOCK 0x2
	mprGC flag to run GC if ncessary and return without yielding.
#define	MPR_HASH_CASELESS 0x10
	Key comparisons ignore case.
#define	MPR_HASH_STABLE 0x400
	Contents are stable or only accessed by one thread.
#define	MPR_HASH_STATIC_KEYS 0x40
	Keys are permanent - don't dup or mark.
#define	MPR_HASH_STATIC_VALUES 0x80
	Values are permanent - don't mark.
#define	MPR_HASH_UNICODE 0x20
	Hash keys are unicode strings.
#define	MPR_HASH_UNIQUE 0x200
	Add to existing will fail.
#define	MPR_HTTP_DATE "%a, %d %b %Y %T GMT"
	Date format for use in HTTP (headers).
#define	MPR_INFO 2
	Configuration settings trace level.
#define	MPR_INFO_MSG 0x40
	Originated from mprInfo.
#define	MPR_JSON_ARRAY 0x2
	The property is an array.
#define	MPR_JSON_DUPLICATE 0x8
	Permit duplicate properties of the same name.
#define	MPR_JSON_FALSE 0x8
	The property is false.
#define	MPR_JSON_NULL 0x10
	The property is null.
#define	MPR_JSON_NUMBER 0x20
	The property is a number.
#define	MPR_JSON_OBJ 0x1
	The property is an object.
#define	MPR_JSON_OVERWRITE 0x1
	Overwrite existing properties.
#define	MPR_JSON_PRETTY 0x1
	Serialize output in a more human readable, multiline "pretty" format.
#define	MPR_JSON_QUOTES 0x2
	Serialize output quoting keys.
#define	MPR_JSON_REGEXP 0x40
	The property is a regular expression.
#define	MPR_JSON_REMOVE 0x1
	Remove matching properties.
#define	MPR_JSON_SIMPLE 0x2
	Simple property names without query expressions.
#define	MPR_JSON_STRING 0x80
	The property is a string.
#define	MPR_JSON_STRINGS 0x4
	Emit all values as quoted strings.
#define	MPR_JSON_TOP 0x4
	Query top level properties only.
#define	MPR_JSON_TRUE 0x100
	The property is true.
#define	MPR_JSON_UNDEFINED 0x200
	The property is undefined.
#define	MPR_JSON_VALUE 0x4
	The property is a value (false\|true\|null\|undefined\|regexp\|number\|string).
#define	MPR_LEVEL_MASK 0xf
	Level mask.
#define	MPR_LIST_STABLE 0x40
	Contents are stable or only accessed by one thread.
#define	MPR_LIST_STATIC_VALUES 0x20
	Flag for mprCreateList when values are permanent.
#define	MPR_LOCAL_TIMEZONE MAXINT
	Constants for mprParseTime.
#define	MPR_LOG_ANEW 0x20
	Start anew on boot (rotate).
#define	MPR_LOG_APPEND 0x10
	Append to existing log files.
#define	MPR_LOG_MSG 0x80
	Originated from mprLog.
#define	MPR_MANAGE_FREE 0x1
	Block being freed.
#define	MPR_MANAGE_MARK 0x2
	Block being marked by GC.
#define	MPR_MAX_FILE 256
	Maximum number of files to close when forking.
#define	MPR_MEM_FAIL 0x4
	Memory allocation failed - immediate exit.
#define	MPR_MEM_LIMIT 0x2
	Memory use exceeds memory limit - invoking policy.
#define	MPR_MEM_TOO_BIG 0x4
	Memory allocation request is too big - immediate exit.
#define	MPR_MEM_WARNING 0x1
	Memory use exceeds warnHeap level limit.
#define	MPR_MIN_TIME_FOR_GC 2
	Wait till 2 milliseconds of idle time possible.
#define	MPR_MODULE_STARTED 0x1
	Module stared.
#define	MPR_MODULE_STOPPED 0x2
	Module stopped.
#define	MPR_NO_WINDOW 0x4
	Don't create a windows Window.
#define	MPR_NORMAL_PRIORITY 50
	Normal (default) priority.
#define	MPR_OBJ_HASH 0x1
	Object is a hash.
#define	MPR_OBJ_LIST 0x1
	Object is a hash.
#define	MPR_PATH_DEPTH_FIRST 0x2
	Flag for mprGetPathFiles to do a depth-first traversal.
#define	MPR_PATH_DESCEND 0x1
	Flag for mprGetPathFiles to traverse subdirectories.
#define	MPR_PATH_INC_HIDDEN 0x4
	Flag for mprGetPathFiles to include hidden files.
#define	MPR_PATH_NODIRS 0x8
	Flag for mprGetPathFiles to exclude subdirectories.
#define	MPR_PATH_RELATIVE 0x10
	Flag for mprGetPathFiles to return paths relative to the directory.
#define	MPR_PROTO_ALL 0x1F
	All SSL protocols.
#define	MPR_PROTO_SSLV2 0x1
	SSL V2 protocol.
#define	MPR_PROTO_SSLV3 0x2
	SSL V3 protocol.
#define	MPR_PROTO_TLSV1 0x4
	TLS V1 protocol.
#define	MPR_PROTO_TLSV11 0x8
	TLS V1.1 protocol.
#define	MPR_PROTO_TLSV12 0x10
	TLS V1.2 protocol.
#define	MPR_RAW_MSG 0x100
	Raw message output.
#define	MPR_READABLE 0x2
	Read event mask.
#define	MPR_REQUEST_PRIORITY 50
	Normal priority.
#define	MPR_RFC3399_DATE "%FT%TZ"
	Date format for RFC 3399 for use in HTML 5.
#define	MPR_RFC_DATE "%a, %d %b %Y %T %Z"
	Format a date according to RFC822: (Fri, 07 Jan 2003 12:12:21 PDT).
#define	MPR_SERVICE_NO_BLOCK 0x4
	Do not block in mprServiceEvents.
#define	MPR_SERVICE_NO_GC 0x8
	Don't run GC.
#define	MPR_SERVICE_ONE_THING MPR_SERVICE_NO_BLOCK
	Wait for one event or one I/O.
#define	MPR_SIGNAL_AFTER 0x2
	Flag to mprAddSignalHandler to run handler after existing handlers.
#define	MPR_SIGNAL_BEFORE 0x1
	Flag to mprAddSignalHandler to run handler before existing handlers.
#define	MPR_SOCKET_BLOCK 0x1
	Use blocking I/O.
#define	MPR_SOCKET_BROADCAST 0x2
	Broadcast mode.
#define	MPR_SOCKET_BUFFERED_READ 0x800
	Socket has buffered read data (in SSL stack).
#define	MPR_SOCKET_BUFFERED_WRITE 0x1000
	Socket has buffered write data (in SSL stack).
#define	MPR_SOCKET_CHECKED 0x2000
	Peer certificate has been checked.
#define	MPR_SOCKET_CLOSED 0x4
	MprSocket has been closed.
#define	MPR_SOCKET_CONNECTING 0x8
	MprSocket is connecting.
#define	MPR_SOCKET_DATAGRAM 0x10
	Use datagrams.
#define	MPR_SOCKET_DISCONNECTED 0x4000
	The mprDisconnectSocket has been called.
#define	MPR_SOCKET_EOF 0x20
	Seen end of file.
#define	MPR_SOCKET_GRACEFUL 1
	Do a graceful shutdown.
#define	MPR_SOCKET_HANDSHAKING 0x8000
	Doing an SSL handshake.
#define	MPR_SOCKET_LISTENER 0x40
	MprSocket is server listener.
#define	MPR_SOCKET_NODELAY 0x100
	Disable Nagle algorithm.
#define	MPR_SOCKET_NOREUSE 0x80
	Don't set SO_REUSEADDR option.
#define	MPR_SOCKET_SERVER 0x400
	Socket is on the server-side.
#define	MPR_SOCKET_THREAD 0x200
	Process callbacks on a worker thread.
#define	MPR_STARTED 2
	Applicationa and MPR services started.
#define	MPR_STOPPED 4
	App is idle and now stopped.
#define	MPR_STOPPING 3
	App has been instructed to shutdown.
#define	MPR_TICKS_PER_SEC 1000
	Time ticks per second.
#define	MPR_TIMEOUT_GC_SYNC 100
	Short wait period for threads to synchronize.
#define	MPR_TIMEOUT_LINGER 2000
	Close socket linger timeout.
#define	MPR_TIMEOUT_NAP 20
	Short pause.
#define	MPR_TIMEOUT_NO_BUSY 1000
	Wait period to minimize CPU drain.
#define	MPR_TIMEOUT_PRUNER 120000
	Time between worker thread pruner runs (2 min).
#define	MPR_TIMEOUT_START_TASK 10000
	Time to start tasks running.
#define	MPR_TIMEOUT_STOP 30000
	Default wait when stopping resources (30 sec).
#define	MPR_TIMEOUT_STOP_TASK 10000
	Time to stop or reap tasks (vxworks).
#define	MPR_TIMEOUT_WORKER 60000
	Prune worker that has been idle for 1 min.
#define	MPR_TRACE_MSG 0x200
	Originated from mprTrace.
#define	MPR_TRIM_BOTH 0x3
	Flag for strim to trim from both the start and the end of the string.
#define	MPR_TRIM_END 0x2
	Flag for strim to trim from the end of the string.
#define	MPR_TRIM_START 0x1
	Flag for strim to trim from the start of the string.
#define	MPR_USER_EVENTS_THREAD 0x2
	User will explicitly manage own mprServiceEvents calls.
#define	MPR_UTC_TIMEZONE 0
	Use UTC timezone.
#define	MPR_VERBOSE 9
	Highest level of trace.
#define	MPR_WAIT_IMMEDIATE 0x4
	Wait handler flag to immediately service event on same thread.
#define	MPR_WAIT_NEW_DISPATCHER 0x2
	Wait handler flag to create a new dispatcher for each I/O event.
#define	MPR_WAIT_NOT_SOCKET 0x8
	I/O file descriptor is not a socket - windows will ignore.
#define	MPR_WAIT_RECALL_HANDLER 0x1
	Wait handler flag to recall the handler asap.
#define	MPR_WARN 1
	Soft warning trace level.
#define	MPR_WARN_MSG 0x400
	Originated from mprWarn.
#define	MPR_WORKER_BUSY 0x1
	Worker currently running to a callback.
#define	MPR_WORKER_IDLE 0x4
	Worker is sleeping (idle) on idleCond.
#define	MPR_WORKER_PRIORITY 50
	Normal priority.
#define	MPR_WORKER_PRUNED 0x2
	Worker has been pruned and will be terminated.
#define	MPR_WRITABLE 0x4
	Write event mask.
#define	MPR_XML_AFTER_LS 2
	Seen "<".
#define	MPR_XML_ATT_EQ 6
	Seen "<tag att" =.
#define	MPR_XML_ATT_NAME 5
	Seen "<tag att".
#define	MPR_XML_BEGIN 1
	Before next tag.
#define	MPR_XML_CDATA 13
	Seen "<![CDATA[" U.
#define	MPR_XML_COMMENT 3
	Seen "<!–" (usr) U.
#define	MPR_XML_ELT_DATA 10
	Seen "<tag>....<" U.
#define	MPR_XML_ELT_DEFINED 9
	Seen "<tag...>" U.
#define	MPR_XML_END_ELT 11
	Seen "<tag>....</tag>" U.
#define	MPR_XML_EOF -2
	End of input.
#define	MPR_XML_ERR -1
	Error.
#define	MPR_XML_NEW_ATT 7
	Seen "<tag att = "val" U.
#define	MPR_XML_NEW_ELT 4
	Seen "<tag" (usr) U.
#define	MPR_XML_PI 12
	Seen "<?processingInst" U.
#define	MPR_XML_SOLO_ELT_DEFINED 8
	Seen "<tag../>" U.
#define	MPR_YIELD_COMPLETE 0x1
	mprYield flag to wait until the GC entirely completes including sweep phase.
#define	MPR_YIELD_DEFAULT 0x0
	mprYield flag if GC is required, yield and wait for mark phase to coplete, otherwise return without blocking.
#define	MPR_YIELD_STICKY 0x2
	mprYield flag to yield and remain yielded until reset.
#define	tassert assertTrue(gp, MPR_LOC, C, #C)
	Assert macro for use by unit tests.
#define	tassert assertTrue(gp, MPR_LOC, C, #C)
	Assert macro for use by unit tests.

int	busy	Number of busy workers.
int	idle	Number of idle workers.
int	max	Configured max number of workers.
int	maxUsed	Max number of workers ever used used.
int	min	Configured minimum number of workers.
int	yielded	Number of busy workers yielded for GC.

MPR - MPR API Native API

Description:

Components

Functions

Typedefs

Defines

Mpr

MprBuf

MprCache

MprCmd

MprDispatcher

MprEvent

MprFile

MprFileSystem

MprFloat

MprHash

MprJson

MprList

MprLog

MprMem

MprMime

MprModule

MprModuleSerivce

MprPath

MprSignal

MprSocket

MprSsl

MprString

MprSync

MprTestService

MprThread

MprTime

MprWaitHandler

MprWorker

MprXml

Functions

Typedefs